Merge pull request #942 from harpocrates/update-docs

Fix & add to documentation

doc/cheatsheet/haddocks.md

@@ -85,7 +85,7 @@ definitions with "[thing]"
   -- \[
   --   f(n) = \Sum_{i=1}^{n} i
   -- \]
-  \\ when \(n > 0\)
+  -- when \(n > 0\)
 ```
 
 # Headings in Documentation

doc/invoking.rst

@@ -27,8 +27,8 @@ considered a bug in the new versions. If you ever get failed parsing
 message, please report it.
 
 You must also specify an option for the output format. Currently only
-the :option:`--html` option for HTML and the :option:`--hoogle` option for
-outputting Hoogle data are functional.
+the :option:`--html` option for HTML, the :option:`--hoogle` option for
+outputting Hoogle data, and the :option:`--latex` option are functional.
 
 The packaging tool
 `Cabal <http://www.haskell.org/ghc/docs/latest/html/Cabal/index.html>`__
@@ -124,6 +124,12 @@ The following options are available:
         Some JavaScript utilities used to implement some of the dynamic
         features like collapsible sections.
 
+.. option:: --mathjax
+
+    Specify a custom URL for a mathjax-compatible JS script. By default,
+    this is set to `MathJax
+    <https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML>`_.
+
 .. option:: --latex
 
     Generate documentation in LaTeX format. Several files will be
@@ -159,6 +165,35 @@ The following options are available:
 
     Generate an index file for the
     `Hoogle <http://hackage.haskell.org/package/hoogle>`_ search engine.
+    One text file will be generated into the current directory (or the
+    specified directory if the :option:`-o` is given). Note that
+    the :option:`--package-name` is required.
+
+    Since the output is intended to be parsed by Hoogle, some conventions
+    need to be upheld:
+
+      * Every entity should span exactly one line. ::
+
+            newtype ReaderT r (m :: * -> *) a :: * -> (* -> *) -> * -> *
+          
+        The one exception to this rule is classes. The body of a class
+        is split up with one class member per line, an opening brace on
+        the line of the header, and a closing brace on a new line after
+        the class. ::
+
+            class Foo a where {
+                foo :: a -> a -> Baz a;
+                type family Baz a;
+                type Baz a = [(a, a)];
+            }
+      
+      * Entites that are exported only indirectly (for instance data
+        constructors visible via a ``ReaderT(..)`` export) have their names
+        wrapped in square brackets. ::
+
+            [ReaderT] :: (r -> m a) -> ReaderT r m a
+            [runReaderT] :: ReaderT r m a -> r -> m a
+
 
 .. option:: --hyperlinked-source
 
@@ -341,6 +376,14 @@ The following options are available:
 
     The title should be a plain string (no markup please!).
 
+.. option:: --package-name=<name>
+
+    Specify the name of the package being documented.
+
+.. option:: --package-version=<version>
+
+    Specify the version of the package being documented.
+
 .. option:: -q <mode>
             --qual=<mode>
 
@@ -368,6 +411,19 @@ The following options are available:
 
     -  relative: x, B.y, C.z
 
+.. option:: --since-qual=<mode>
+
+    Specify how ``@since`` annotations are qualified.
+
+    mode should be one of
+
+    -  ``always`` (default): always qualify ``@since`` annotations with
+       a package name and version
+
+    -  ``only-external``: only qualify ``@since`` annotations with a
+       package name and version when they do not come from the current
+       package
+
 .. option:: -?
             --help
 
@@ -378,6 +434,21 @@ The following options are available:
 
     Output version information and exit.
 
+.. option:: --ghc-version
+
+    Output the version of GHC which Haddock expects to find at :option:-B
+    and exit.
+
+.. option:: --print-ghc-path
+
+    Output the path to the GHC (which Haddock computes based on :option:-B)
+    and exit.
+
+.. option:: --print-ghc-libdir
+
+    Output the path to the GHC ``lib`` directory (which Haddock computes
+    based on :option:-B) and exit.
+
 .. option:: -v
             --verbose
 
@@ -415,6 +486,16 @@ The following options are available:
     Causes Haddock to behave as if module module has the ``hide``
     attribute. (:ref:`module-attrs`).
 
+.. option:: --show <module>
+
+    Causes Haddock to behave as if module module does not have the ``hide``
+    attribute. (:ref:`module-attrs`).
+
+.. option:: --show-all
+
+    Causes Haddock to behave as if no modules have the ``hide`` attribute.
+    (:ref:`module-attrs`).
+
 .. option:: --show-extensions <module>
 
     Causes Haddock to behave as if module module has the
@@ -430,10 +511,21 @@ The following options are available:
 
     Turn off all warnings.
 
+.. option:: --interface-version
+
+    Prints out the version of the binary Haddock interface files that
+    this version of Haddock generates.
+
 .. option:: --compatible-interface-versions
 
     Prints out space-separated versions of binary Haddock interface
-    files that this version is compatible with.
+    files that this version of Haddock is compatible with.
+
+.. option:: --bypass-interface-version-check
+
+    **DANGEROUS** Causes Haddock to ignore the interface verions of
+    binary Haddock interface files. This can make Haddock crash during
+    deserialization of interface files.
 
 .. option:: --no-tmp-comp-dir
 

doc/markup.rst

@@ -8,6 +8,8 @@ will just generate documentation that contains the type signatures, data
 type declarations, and class declarations exported by each of the
 modules being processed.
 
+.. _top-level-declaration
+
 Documenting a Top-Level Declaration
 -----------------------------------
 
@@ -47,6 +49,8 @@ the following:
 
 -  A ``class`` declaration,
 
+-  An ``instance`` declaration,
+
 -  A ``data family`` or ``type family`` declaration, or
 
 -  A ``data instance`` or ``type instance`` declaration.
@@ -106,6 +110,8 @@ signatures, by using either the ``-- |`` or ``-- ^`` annotations: ::
        -- | This is the documentation for the 'g' method
        g :: Int -> a
 
+Associated type and data families can also be annotated in this way.
+
 Constructors and Record Fields
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -166,6 +172,32 @@ would join up documentation of each field and render the result. The
 reason for this seemingly weird behaviour is the fact that ``someField``
 is actually the same (partial) function.
 
+Deriving clauses
+~~~~~~~~~~~~~~~~
+
+Most instances are top-level, so can be documented as in
+:ref:`top-level-declaration`. The exception to this is instance that are
+come from a ``deriving`` clause on a datatype declaration. These can
+the documented like this: ::
+
+    data D a = L a | M
+      deriving ( Eq   -- ^ @since 4.5
+               , Ord  -- ^ default 'Ord' instance
+               )
+
+This also scales to the various GHC extensions for deriving: ::
+
+    newtype T a = T a
+      deriving          Show     -- ^ derivation of 'Show'
+      deriving stock  ( Eq       -- ^ stock derivation of 'Eq'
+                      , Foldable -- ^ stock derivation of 'Foldable'
+                      )
+      deriving newtype  Ord      -- ^ newtype derivation of 'Ord'
+      deriving anyclass Read     -- ^ unsafe derivation of 'Read'
+      deriving        ( Eq1      -- ^ deriving 'Eq1' via 'Identity'
+                      , Ord1     -- ^ deriving 'Ord1' via 'Identity'
+                      ) via Identity
+
 Function Arguments
 ~~~~~~~~~~~~~~~~~~
 
@@ -175,8 +207,8 @@ 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.
+Pattern synonyms, GADT-style data constructors, and class methods also
+support this style of documentation.
 
 .. _module-description:
 
@@ -890,8 +922,14 @@ necessary to escape the single quote when used as an apostrophe: ::
 
 Nothing special is needed to hyperlink identifiers which contain
 apostrophes themselves: to hyperlink ``foo'`` one would simply type
-``'foo''``. To hyperlink identifiers written in infix form, simply put
-them in quotes as always: ``'`elem`'``.
+``'foo''``. Hyperlinking operators works in exactly the same way.
+
+Note that it is not possible to directly hyperlink an identifier in infix
+form or an operator in prefix form. The next best thing to do is to wrap
+the whole identifier in monospaced text and put the parentheses/backticks
+outside of the identifier, but inside the link: ::
+
+    -- | A prefix operator @('++')@ and an infix identifier @\``elem`\`@.
 
 Emphasis, Bold and Monospaced Text
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~