Create Haddocks from entity documentation comments#1503
Create Haddocks from entity documentation comments#1503parsonsmatt merged 10 commits intoyesodweb:masterfrom
Conversation
|
This is fantastic, thanks! Can you clarify the limitatiion around documenting fields? Can you post the problematic test? That smells like a GHC bug to me, and might be worth reporting upstream. For a test, I'd be happy to see a rendered Haddock that contains the docs - a screenshout would be fine. |
|
On closer inspection, the limitation only applies to |
Previously, field Haddocks would only be processed if a documentation comment was present on the model. This commit also uses putDoc for both field and model Haddocks, removing the withDecDoc import.
|
Regarding version bumping, would this change require a minor version bump (to Also, would it be worth addressing #1296 and #1297 (and merging #1505) before releasing this change so that documentation comments are syntactically equivalent to the format supported by Haddock? Alternatively, these issues could be fixed and released in subsequent patch versions if frequent releases aren't a problem. |
|
This would be a minor version bump, which put be I think I'd be fine releasing this separately from changing the way the comment syntax works. |
|
You can do either; I generally find that merges make viewing diffs slightly easier on GitHub since I can see "changes since last review," but you're right that it'll get squash/merged into |
2 participants
This PR adds a flag to
MkPersistSettingswhich enables Haddock generation from entity documentation comments. The default isFalseto avoid any unexpected performance impacts from upgradingpersistent.Fixes #1462.
Before submitting your PR, check that you've:
@sincedeclarations to the Haddockpersistentversion2.14.6.0.stylish-haskellon any changed files.stylish-haskellfails on the#if-#else-#endifconstruct in the import list inTH.hsas all three preprocessor directives are ignored, resulting in two identifier lists forLanguage.Haskell.TH.Lib..editorconfigfile for details)After submitting your PR:
(unreleased)on the Changelog