Chapter 3. Documentation and Markup
Prev |  | Next

# Chapter 3. 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.

## 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:

- A type signature for a top-level function,

- 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

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

Prev |  | Next
Chapter 2. Invoking Haddock | Home | 3.2. Documenting parts of a declaration