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.

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