diff options
author | Alec Theriault <alec.theriault@gmail.com> | 2018-01-13 03:12:37 -0800 |
---|---|---|
committer | Alexander Biehl <alexbiehl@gmail.com> | 2018-01-13 12:12:37 +0100 |
commit | aa33be50e6292875b6afea8f97980c3a6e76ed87 (patch) | |
tree | 8ef2dc71b1f65ed3fedd435f56e1ac7d520e3460 /doc | |
parent | 24841386cff6fdccc11accf9daa815c2c7444d65 (diff) |
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.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/markup.rst | 14 |
1 files changed, 14 insertions, 0 deletions
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 @@ -118,6 +120,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 |