Chapter 3. Documentation and Markup

Table of Contents

3.1. Documenting a top-level declaration
3.2. Documenting parts of a declaration
3.2.1. Class methods
3.2.2. Constructors and record fields
3.2.3. Function arguments
3.3. The module description
3.4. Controlling the documentation structure
3.4.1. Re-exporting an entire module
3.4.2. Omitting the export list
3.5. Named chunks of documentation
3.6. Hyperlinking and re-exported entities
3.7. Derived instances
3.8. Module Attributes
3.9. Markup
3.9.1. Paragraphs
3.9.2. Special characters
3.9.3. Character references
3.9.4. Code Blocks
3.9.5. Hyperlinked Identifiers
3.9.6. Emphasis and Monospaced text
3.9.7. Linking to modules
3.9.8. Itemized and Enumerated lists
3.9.9. Definition lists
3.9.10. URLs
3.9.11. Images
3.9.12. Anchors

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, or

  • A class 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