From aa33be50e6292875b6afea8f97980c3a6e76ed87 Mon Sep 17 00:00:00 2001 From: Alec Theriault Date: Sat, 13 Jan 2018 03:12:37 -0800 Subject: Constructor and pattern synonym argument docs (#709) * Support Haddocks on constructor arguments This is in conjunction with https://phabricator.haskell.org/D4094. Adds support for rendering Haddock's on (non-record) constructor arguments, both for regular and GADT constructors. * Support haddocks on pattern synonym arguments It appears that GHC already parsed these - we just weren't using them. In the process of doing this, I tried to deduplicate some code around handling patterns. * Update the markup guide Add some information about the new support for commenting constructor arguments, and mention pattern synonyms and GADT-style constructors. * Overhaul LaTeX support for data/pattern decls This includes at least * fixing several bugs that resulted in invalid LaTeX * fixing GADT data declaration headers * overhaul handling of record fields * overhaul handling of GADT constructors * overhaul handling of bundled patterns * add support for constructor argument docs * Support GADT record constructors This means changes what existing HTML docs look like. As for LaTeX, looks like GADT records were never even supported. Now they are. * Clean up code/comments Made code/comments consistent between the LaTeX and XHTML backend when possible. * Update changelog * Patch post-rebase regressions * Another post-rebase change We want return values to be documentable on record GADT constructors. --- doc/markup.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'doc') diff --git a/doc/markup.rst b/doc/markup.rst index d0b9392d..4d56cc83 100644 --- a/doc/markup.rst +++ b/doc/markup.rst @@ -39,6 +39,8 @@ the following: - A ``data`` declaration, +- A ``pattern`` declaration, + - A ``newtype`` declaration, - A ``type`` declaration @@ -117,6 +119,15 @@ Constructors are documented like so: :: or like this: :: + data T a b + = C1 -- ^ This is the documentation for the 'C1' constructor + a -- ^ This is the documentation for the argument of type 'a' + b -- ^ This is the documentation for the argument of type 'b' + +There is one edge case that is handled differently: only one ``-- ^`` +annotation occuring after the constructor and all its arguments is +applied to the constructor, not its last argument: :: + data T a b = C1 a b -- ^ This is the documentation for the 'C1' constructor | C2 a b -- ^ This is the documentation for the 'C2' constructor @@ -164,6 +175,9 @@ Individual arguments to a function may be documented like this: :: -> Float -- ^ The 'Float' argument -> IO () -- ^ The return value +Pattern synonyms and GADT-style data constructors also support this +style of documentation. + .. _module-description: The Module Description -- cgit v1.2.3