aboutsummaryrefslogtreecommitdiff
path: root/doc/markup.rst
diff options
context:
space:
mode:
authorAlec Theriault <alec.theriault@gmail.com>2018-01-13 03:12:37 -0800
committerAlexander Biehl <alexbiehl@gmail.com>2018-01-13 12:12:37 +0100
commitaa33be50e6292875b6afea8f97980c3a6e76ed87 (patch)
tree8ef2dc71b1f65ed3fedd435f56e1ac7d520e3460 /doc/markup.rst
parent24841386cff6fdccc11accf9daa815c2c7444d65 (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/markup.rst')
-rw-r--r--doc/markup.rst14
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