3.3. The module description

A module itself may be documented with multiple fields that can then be displayed by the backend. In particular, the HTML backend displays all the fields it currently knows about. We first show the most complete module documentation example and then talk about the fields.

{-|
Module      : W
Description : Short description
Copyright   : (c) Some Guy, 2013
                  Someone Else, 2014
License     : GPL-3
Maintainer  : [email protected]
Stability   : experimental
Portability : POSIX

Here is a longer description of this module, containing some
commentary with @some markup@.
-}
module W where
...

The Module field should be clear. It currently doesn't affect the output of any of the backends but you might want to include it for human information or for any other tools that might be parsing these comments without the help of GHC.

The Description field accepts some short text which outlines the general purpose of the module. If you're generating HTML, it will show up next to the module link in the module index.

The Copyright, License, Maintainer and Stability fields should be obvious. An alternative spelling for the License field is accepted as Licence but the output will always prefer License.

The Portability field has seen varied use by different library authors. Some people put down things like operating system constraints there while others put down which GHC extensions are used in the module. Note that you might want to consider using the show-extensions module flag for the latter.

Finally, a module may contain a documentation comment before the module header, in which case this comment is interpreted by Haddock as an overall description of the module itself, and placed in a section entitled Description in the documentation for the module. All usual Haddock markup is valid in this comment.

All fields are optional but they must be in order if they do appear. Multi-line fields are accepted but the consecutive lines have to start indented more than their label. If your label is indented one space as is often the case with -- syntax, the consecutive lines have to start at two spaces at the very least. Please note that we do not enforce the format for any of the fields and the established formats are just a convention.