aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/cheatsheet/haddocks.md2
-rw-r--r--doc/invoking.rst98
-rw-r--r--doc/markup.rst46
3 files changed, 138 insertions, 8 deletions
diff --git a/doc/cheatsheet/haddocks.md b/doc/cheatsheet/haddocks.md
index a3464584..5ee285b3 100644
--- a/doc/cheatsheet/haddocks.md
+++ b/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
diff --git a/doc/invoking.rst b/doc/invoking.rst
index acdba9bd..e6612000 100644
--- a/doc/invoking.rst
+++ b/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
diff --git a/doc/markup.rst b/doc/markup.rst
index 4e00f708..9fb0209a 100644
--- a/doc/markup.rst
+++ b/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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~