Haddock

Contents

There is only Haddock
Your types
Your comments
Structure!

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.

Your types

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

Your comments

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, xs and xss in the following Haddock comment:

{- | @intercalate xs xss@ inserts the list @xs@ in between the lists in @xss@ and concatenates the result. -}

Structure!

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.

module Your.Module.Name
  (

  -- The module export list consists
  -- of everything inside the parens.
  -- This is where you control the
  -- Haddock document structure.

  ) where

Document order

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.

Section headings

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.

module Network.Wreq
  (
  -- * HTTP verbs
  -- ** GET
    get
  , getWith
  -- ** POST
  , post
  , postWith

  -- * Configuration
  , Options
  , defaults
  -- ** Authentication
  , Auth, basicAuth, oauth1Auth
  , oauth2Bearer, oauth2Token
  -- ** Proxy settings
  , Proxy (..), httpProxy
  )

HTTP verbs
- GET
- POST
Configuration
- Authentication
- Proxy settings

Join Type Classes for courses and projects to get you started and make you an expert in FP with Haskell.