Chapter 3. Documentation and Markup

Table of Contents
3.1. Documenting a top-level declaration
3.2. Documenting parts of a declaration
3.3. The module description
3.4. Controlling the documentation structure
3.5. Named chunks of documentation
3.6. Hyperlinking and re-exported entities
3.7. Module Attributes
3.8. 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.

3.1. 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:

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

Note that Haddock doesn't contain a Haskell type system — if you don't write the type signature for a function, then Haddock can't tell what its type is and it won't be included in the documentation.

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