3.4. Controlling the documentation structure

Haddock produces interface documentation that lists only the entities actually exported by the module. The documentation for a module will include all entities exported by that module, even if they were re-exported by 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.

However, 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.

You can insert headings and sub-headings in the documentation by including annotations at the appropriate point in the 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. eg.:

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

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

module A (
  module B,
  module C
 ) where

What will the Haddock-generated documentation for this module look like? Well, it depends on how the modules B and C are imported. If they are imported wholly and without any hiding qualifiers, then the documentation will just contain a cross-reference to the documentation for B and C. However, if the modules are not completely re-exported, for example:

module A (
  module B,
  module C
 ) where

import B hiding (f)
import C (a, b)

then Haddock behaves as if the set of entities re-exported from B and C had been listed explicitly in the export list[2].

The exception to this rule is when the re-exported module is declared with the hide attribute (Section 3.7, “Module Attributes”), in which case the module is never cross-referenced; the contents are always expanded in place in the re-exporting module.

3.4.2. Omitting the export list

If there is no export list in the module, how does Haddock generate documentation? Well, when the export list is omitted, e.g.:

module Foo where

this is equivalent to an export list which mentions every entity defined at the top level in this module, and Haddock treats it in the same way. Furthermore, the generated documentation will retain the order in which entities are defined in the module. In this special case the module body may also include section headings (normally they would be ignored by Haddock).



[2] NOTE: this is not fully implemented at the time of writing (version 0.2). At the moment, Haddock always inserts a cross-reference.