Skip to content
Snippets Groups Projects
Commit 7f4d887b authored by Alec Theriault's avatar Alec Theriault
Browse files

Fix/add to various docs

* Add documentation for a bunch of previously undocumented
  options (fixes #870)
* Extend the documentation of `--hoogle` considerably (see #807)
* Describe how to add docs to `deriving` clauses (fixes #912)
* Fix inaccurate docs about hyperlinking infix identifiers (fixes #780)
parent 8635e4b9
No related branches found
No related tags found
No related merge requests found
......@@ -85,7 +85,7 @@ definitions with "[thing]"
-- \[
-- f(n) = \Sum_{i=1}^{n} i
-- \]
\\ when \(n > 0\)
-- when \(n > 0\)
```
# Headings in Documentation
......
......@@ -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
......
......@@ -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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment