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 : sample@email.com 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.