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
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
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
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
had been listed explicitly in the export
The exception to this rule is when the re-exported
module is declared with the
(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.
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).
module Foo where -- * This heading will now appear before foo. -- | Documentation for 'foo'. foo :: Integer foo = 5
 NOTE: this is not fully implemented at the time of writing (version 0.2). At the moment, Haddock always inserts a cross-reference.