markup.rst

Documentation and Markup
========================

Haddock understands special documentation annotations in the Haskell
source file and propagates these into the generated documentation. The
annotations are purely optional: if there are no annotations, Haddock
will just generate documentation that contains the type signatures, data
type declarations, and class declarations exported by each of the
modules being processed.

Documenting a Top-Level Declaration
-----------------------------------

The simplest example of a documentation annotation is for documenting
any top-level declaration (function type signature, type declaration, or
class declaration). For example, if the source file contains the
following type signature: ::

square :: Int -> Int
square x = x * x

Then we can document it like this: ::

-- |The 'square' function squares an integer.
square :: Int -> Int
square x = x * x

The ``-- |`` syntax begins a documentation annotation, which applies
to the *following* declaration in the source file. Note that the
annotation is just a comment in Haskell — it will be ignored by the
Haskell compiler.

The declaration following a documentation annotation should be one of
the following:

- A type signature for a top-level function,

- A definition for a top-level function with no type signature,

- A ``data`` declaration,

- A ``newtype`` declaration,

- A ``type`` declaration

- A ``class`` declaration,

- A ``data family`` or ``type family`` declaration, or

- A ``data instance`` or ``type instance`` declaration.

If the annotation is followed by a different kind of declaration, it
will probably be ignored by Haddock.

Some people like to write their documentation *after* the declaration;
this is possible in Haddock too: ::

square :: Int -> Int
-- ^The 'square' function squares an integer.
square x = x * x

Since Haddock uses the GHC API internally, it can infer types for
top-level functions without type signatures. However, you're
encouraged to add explicit type signatures for all top-level
functions, to make your source code more readable for your users, and
at times to avoid GHC inferring overly general type signatures that
are less helpful to your users.

Documentation annotations may span several lines; the annotation
continues until the first non-comment line in the source file. For
example: ::

-- |The 'square' function squares an integer.
-- It takes one argument, of type 'Int'.
square :: Int -> Int
square x = x * x

You can also use Haskell's nested-comment style for documentation
annotations, which is sometimes more convenient when using multi-line
comments: ::

{-|
The 'square' function squares an integer.
It takes one argument, of type 'Int'.
-}
square :: Int -> Int
square x = x * x

Documenting Parts of a Declaration
----------------------------------

In addition to documenting the whole declaration, in some cases we can
also document individual parts of the declaration.

Class Methods
~~~~~~~~~~~~~

Class methods are documented in the same way as top level type
signatures, by using either the ``-- |`` or ``-- ^`` annotations: ::

class C a where
-- | This is the documentation for the 'f' method
f :: a -> Int
-- | This is the documentation for the 'g' method
g :: Int -> a

Constructors and Record Fields
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Constructors are documented like so: ::

data T a b
-- | This is the documentation for the 'C1' constructor
= C1 a b
-- | This is the documentation for the 'C2' constructor
| C2 a b

or like this: ::

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

Record fields are documented using one of these styles: ::

data R a b =
C { -- | This is the documentation for the 'a' field
a :: a,
-- | This is the documentation for the 'b' field
b :: b
}

data R a b =
C { a :: a -- ^ This is the documentation for the 'a' field
, b :: b -- ^ This is the documentation for the 'b' field
}

Alternative layout styles are generally accepted by Haddock - for
example doc comments can appear before or after the comma in separated
lists such as the list of record fields above.

In case that more than one constructor exports a field with the same
name, the documentation attached to the first occurence of the field
will be used, even if a comment is not present. ::

data T a = A { someField :: a -- ^ Doc for someField of A
}
| B { someField :: a -- ^ Doc for someField of B
}

In the above example, all occurences of ``someField`` in the
documentation are going to be documented with
``Doc for someField of A``. Note that Haddock versions 2.14.0 and before
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.

Function Arguments
~~~~~~~~~~~~~~~~~~

Individual arguments to a function may be documented like this: ::

f :: Int -- ^ The 'Int' argument
-> Float -- ^ The 'Float' argument
-> IO () -- ^ The return value

.. _module-description:

The Module Description
----------------------

A module itself may be documented with multiple fields that can then be
displayed by the backend. In particular, the HTML backend displays all
the fields it currently knows about. We first show the most complete
module documentation example and then talk about the fields. ::

{-|
Module : W
Description : Short description
Copyright : (c) Some Guy, 2013
Someone Else, 2014
License : GPL-3
Maintainer : sample@email.com
Stability : experimental
Portability : POSIX

Here is a longer description of this module, containing some
commentary with @some markup@.
-}
module W where
...

All fields are optional but they must be in order if they do appear.
Multi-line fields are accepted but the consecutive lines have to start
indented more than their label. If your label is indented one space as
is often the case with the ``--`` syntax, the consecutive lines have
to start at two spaces at the very least. For example, above we saw a
multiline ``Copyright`` field: ::

{-|
...
Copyright : (c) Some Guy, 2013
Someone Else, 2014
...
-}

That could equivalently be written as ::

-- | ...
-- Copyright:
-- (c) Some Guy, 2013
-- Someone Else, 2014
-- ...

or as ::

-- | ...
-- Copyright: (c) Some Guy, 2013
-- Someone Else, 2014
-- ...

but not as ::

-- | ...
-- Copyright: (c) Some Guy, 2013
-- Someone Else, 2014
-- ...

since the ``Someone`` needs to be indented more than the
``Copyright``.

Whether new lines and other formatting in multiline fields is
preserved depends on the field type. For example, new lines in the
``Copyright`` field are preserved, but new lines in the
``Description`` field are not; leading whitespace is not preserved in
either [#backend]_. Please note that we do not enforce the format for
any of the fields and the established formats are just a convention.

.. [#backend] Technically, whitespace and newlines in the
``Description`` field are preserved verbatim by the HTML backend,
but because most browsers collapse whitespace in HTML, they don't
render as such. But other backends may render this whitespace.

Fields of the Module Description
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``Module`` field specifies the current module name. Since the module
name can be inferred automatically from the source file, it doesn't
affect the output of any of the backends. But you might want to
include it for any other tools that might be parsing these comments
without the help of GHC.

The ``Description`` field accepts some short text which outlines the
general purpose of the module. If you're generating HTML, it will show
up next to the module link in the module index.

The ``Copyright``, ``License``, ``Maintainer`` and ``Stability`` fields should
be obvious. An alternative spelling for the ``License`` field is accepted
as ``Licence`` but the output will always prefer ``License``.

The ``Portability`` field has seen varied use by different library
authors. Some people put down things like operating system constraints
there while others put down which GHC extensions are used in the module.
Note that you might want to consider using the ``show-extensions`` module
flag for the latter (see :ref:`module-attrs`).

Finally, a module may contain a documentation comment before the
module header, in which case this comment is interpreted by Haddock as
an overall description of the module itself, and placed in a section
entitled ``Description`` in the documentation for the module. All the
usual Haddock :ref:`markup` is valid in this comment.

Controlling the Documentation Structure
---------------------------------------

Haddock produces interface documentation that lists only the entities
actually exported by the module. If there is no export list then all
entities defined by the module are exported.

The documentation for a module will
include *all* entities exported by that module, even if they were
re-exported from another module. The only exception is when Haddock can't
see the declaration for the re-exported entity, perhaps because it isn't
part of the batch of modules currently being processed.

To Haddock the export list has even more significance than just
specifying the entities to be included in the documentation. It also
specifies the *order* that entities will be listed in the generated
documentation. This leaves the programmer free to implement functions in
any order he/she pleases, and indeed in any *module* he/she pleases, but
still specify the order that the functions should be documented in the
export list. Indeed, many programmers already do this: the export list
is often used as a kind of ad-hoc interface documentation, with
headings, groups of functions, type signatures and declarations in
comments.

In the next section we give examples illustrating most of the
structural markup features. After the examples we go into more detail
explaining the related markup, namely :ref:`section-headings`,
:ref:`named-chunks`, and :ref:`re-exporting-entire-module`.

.. _structure-examples:

Documentation Structure Examples
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

We now give several examples that produce similar results and
illustrate most of the structural markup features. The first two
example use an export list, but the third example does not.

The first example, using an export list with :ref:`section-headings`
and inline section descriptions: ::

module Image
( -- * Image importers
--
-- | There is a "smart" importer, 'readImage', that determines
-- the image format from the file extension, and several
-- "dumb" format-specific importers that decode the file at
-- the specified type.
readImage
, readPngImage
, readGifImage
, ...
-- * Image exporters
-- ...
) where

import Image.Types ( Image )

-- | Read an image, guessing the format from the file name.
readImage :: FilePath -> IO Image
readImage = ...

-- | Read a GIF.
readGifImage :: FilePath -> IO Image
readGifImage = ...

-- | Read a PNG.
readPngImage :: FilePath -> IO Image
readPngImage = ...

...

Note that the order of the entities ``readPngImage`` and
``readGifImage`` in the export list is different from the order of the
actual declarations farther down; the order in the export list is the
order used in the generated docs. Also, the imported ``Image`` type
itself is not re-exported, so it will not be included in the rendered
docs (see :ref:`hyperlinking-re-exported`).

The second example, using an export list with a section description
defined elsewhere (the ``$imageImporters``; see :ref:`named-chunks`):
::

module Image
( -- * Image importers
--
-- $imageImporters
readImage
, readPngImage
, readGifImage
, ...
-- * Image exporters
-- ...
) where

import Image.Types ( Image )

-- $imageImporters
--
-- There is a "smart" importer, 'readImage', that determines the
-- image format from the file extension, and several "dumb"
-- format-specific importers that decode the file at the specified
-- type.

-- | Read an image, guessing the format from the file name.
readImage :: FilePath -> IO Image
readImage = ...

-- | Read a GIF.
readGifImage :: FilePath -> IO Image
readGifImage = ...

-- | Read a PNG.
readPngImage :: FilePath -> IO Image
readPngImage = ...

...

This produces the same rendered docs as the first example, but the
source code itself is arguably more readable, since the documentation
for the group of importer functions is closer to their definitions.

The third example, without an export list: ::

module Image where

import Image.Types ( Image )

-- * Image importers
--
-- $imageImporters
--
-- There is a "smart" importer, 'readImage', that determines the
-- image format from the file extension, and several "dumb"
-- format-specific importers that decode the file at the specified
-- type.

-- | Read an image, guessing the format from the file name.
readImage :: FilePath -> IO Image
readImage = ...

-- | Read a GIF.
readGifImage :: FilePath -> IO Image
readGifImage = ...

-- | Read a PNG.
readPngImage :: FilePath -> IO Image
readPngImage = ...

...

-- * Image exporters
-- ...

Note that the section headers (e.g. ``-- * Image importers``) now
appear in the module body itself, and that the section documentation
is still given using :ref:`named-chunks`. Unlike in the first example
when using an export list, the named chunk syntax ``$imageImporters``
*must* be used for the section documentation; attempting to use the
``-- | ...`` syntax to document the image importers here will wrongly
associate the documentation chunk with the next definition!

.. _section-headings:

Section Headings
~~~~~~~~~~~~~~~~

You can insert headings and sub-headings in the documentation by
including annotations at the appropriate point in the export list, or
in the module body directly when not using an export list.

For example: ::

module Foo (
-- * Classes
C(..),
-- * Types
-- ** A data type
T,
-- ** A record
R,
-- * Some functions
f, g
) where

Headings are introduced with the syntax ``-- *``, ``-- **`` and so
on, where the number of ``*``\ s indicates the level of the heading
(section, sub-section, sub-sub-section, etc.).

If you use section headings, then Haddock will generate a table of
contents at the top of the module documentation for you.

The alternative style of placing the commas at the beginning of each
line is also supported. e.g.: ::

module Foo (
-- * Classes
, C(..)
-- * Types
-- ** A data type
, T
-- ** A record
, R
-- * Some functions
, f
, g
) where

When not using an export list, you may insert section headers in the
module body. Such section headers associate with all entities
declaried up until the next section header. For example: ::

module Foo where

-- * Classes
class C a where ...

-- * Types
-- ** A data type
data T = ...

-- ** A record
data R = ...

-- * Some functions
f :: ...
f = ...
g :: ...
g = ...

.. _re-exporting-entire-module:

Re-Exporting an Entire Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Haskell allows you to re-export the entire contents of a module (or at
least, everything currently in scope that was imported from a given
module) by listing it in the export list: ::