Haddock is the documentation tool for Haskell.
There is only Haddock
Haddock is more intrinsically woven into the ecosystem than most language’s documentation systems; the central package repository, Hackage, generates HTML documentation using only Haddock, and Haddock support is built into Cabal and Stack. You don’t have much choice but to use Haddock if you’re writing a library that you will upload to Hackage.
Automatically, Haddock gives you a page for each module that lists all of the things that the module exports. Some important things it includes are:
- For functions, the argument and return types
- For classes, what types are known to have instances of the class
- For types, what classes the type has an instance for
- For data types, the constructors (if the module exports them)
Each documentation entry also includes a link to the place in the source code where the relevent thing is defined.
Not every Haskell comment gets included; you must specifically mark comments as being Haddock comments for them to be included in the documentation it generates.
A comment that starts with the
|character is a Haddock comment for whatever is defined immediately after it. This is what you typically use for comments on functions, types, and classes.
A comment that starts with the
^character is a Haddock comment for whatever is defined immediately before it. This is what you typically use for comments on function parameters and return types.
Note that the names of your function parameters do not show up in the Haddock documentation. There are two ways to handle this when you need to give names to help your readers understand what each parameter means:
- Specify the names in a Haddock comment on each parameter
- Establish a name for each parameter by starting your prose with a usage example. For example,
xssin the following Haddock comment:
An exciting feature of Haddock is that it doesn’t just present the users of your library with a boring alphabetized list of your types and functions; it lets you organize them into a document with hierarchical section headings and a table of contents.
The export list
All of this happens within the module’s export list. The export list defines the module’s API: which of the things defined in the source file will be visible to code outside of the module.
Everything in the document that Haddock generates is listed according to the ordering of module’s export list; the ordering of the rest of the source code does not have any effect on the documentation.
The way you break the document up into sections is by interspersing section headers among the export list. A comment that starts with one or more
* characters is a header.
* denotes a section,
** denotes a subsection, and so on.This is much like how Markdown uses the
# character for headers.
For example, below we show an example export list and the resulting table of contents that Haddock will generate:This example is from the popular
wreq web client library, though much of it is removed here for brevity.
- HTTP verbs
- Proxy settings