Document foreign and primary keys in the quasiquoter better#1308
Document foreign and primary keys in the quasiquoter better#1308parsonsmatt merged 2 commits intoyesodweb:masterfrom
Conversation
lf-
changed the title
parsonsmatt
left a comment
parsonsmatt
left a comment
There was a problem hiding this comment.
Thank you! This is awesome work and well-needed.
|
|
||
| ## Primary and Foreign keys | ||
|
|
||
| The [tests for this feature](https://github.com/yesodweb/persistent/blob/master/persistent-test/src/CompositeTest.hs#L53) demonstrates their usage |
There was a problem hiding this comment.
oh my god thank you this is fantastic
docs/Persistent-entity-syntax.md
Outdated
| The [tests for composite keys][composite tests] and [tests for foreign keys][foreign tests] have some additional examples. | ||
|
|
||
| [composite tests]: https://github.com/yesodweb/persistent/blob/master/persistent-test/src/CompositeTest.hs#L53 | ||
| [foreign tests]: https://github.com/yesodweb/persistent/blob/master/persistent-test/src/ForeignKey.hs |
There was a problem hiding this comment.
I think we should probably also refer to the Database.Persist.Quasi documentation here, since a lot of this is covered in that too.
We may want to deprecate the entire file here in favor of that 🤔 But it is nice to have multiple points of contact for folks.
There was a problem hiding this comment.
Yes, we probably do! Or merge anything missing into there. I didn't see that module originally, so the document here should at least be replaced with a link to that.
I'm not sure how to make this more discoverable but it very much needs to be. Maybe pointing to it in the readme if it's not already?
There was a problem hiding this comment.
Would you be willing to incorporate your doc additions into the Database.Persist.Quasi module?
From there I think I can try and restructure the Haddocks to point to that more easily. The module docs for Database.Persist... could definitely use some polish and pointing towards this.
There was a problem hiding this comment.
Done. That was painful. Feel free to directly edit anything you'd like on this branch, I'm too tired to poke at it more.
There was a problem hiding this comment.
I'm sorry to hear that it was painful! Thanks for the work you've done, I can take it from here.
There was a problem hiding this comment.
Specifically haddock tables have inspired new levels of frustration with the computer. (oh by the way they're a ghc-8.8 feature, we probably don't care because the rendered docs will be available on the web)
Big pain in the butt to make even with relatively advanced vim shenanigans, and it took a while of fiddling around to get them to actually parse. Turns out you need a paragraph between headings and tables apparently. Grrr.
Also I got to deal with the vim highlighting system seemingly not keeping context from off screen so the highlighting on the doc comment kept getting messed up if I moved by pages at a time. Anyway it's done, and I'll get back to using haddock in a more normal amount 😆.
|
This section got orphaned and I don't know where to put it: |
parsonsmatt
left a comment
parsonsmatt
left a comment
There was a problem hiding this comment.
this is fantastic, thank you so much!
2 participants
I've written some documentation based on poking through the tests and my own use of Persistent. There's more work to do in this file, as there are more sections that just tell you to read a test.