3.9. Markup

Haddock understands certain textual cues inside documentation annotations that tell it how to render the documentation. The cues (or “markup”) have been designed to be simple and mnemonic in ASCII so that the programmer doesn't have to deal with heavyweight annotations when editing documentation comments.

3.9.1. Paragraphs

One or more blank lines separates two paragraphs in a documentation comment.

3.9.2. Special characters

The following characters have special meanings in documentation comments: /, ', `, ", @, <. To insert a literal occurrence of one of these special characters, precede it with a backslash (\).

Additionally, the character > has a special meaning at the beginning of a line, and the following characters have special meanings at the beginning of a paragraph: *, -. These characters can also be escaped using \.

3.9.3. Character references

Although Haskell source files may contain any character from the Unicode character set, the encoding of these characters as bytes varies between systems, so that only source files restricted to the ASCII character set are portable. Other characters may be specified in character and string literals using Haskell character escapes. To represent such characters in documentation comments, Haddock supports SGML-style numeric character references of the forms &#D; and &#xH; where D and H are decimal and hexadecimal numbers denoting a code position in Unicode (or ISO 10646). For example, the references &#x3BB;, &#x3bb; and &#955; all represent the lower-case letter lambda.

3.9.4. Code Blocks

Displayed blocks of code are indicated by surrounding a paragraph with @...@ or by preceding each line of a paragraph with > (we often call these “bird tracks”). For example:

-- | This documentation includes two blocks of code:
--
-- @
--     f x = x + x
-- @
--
-- >  g x = x * 42

There is an important difference between the two forms of code block: in the bird-track form, the text to the right of the ‘>’ is interpreted literally, whereas the @...@ form interprets markup as normal inside the code block.

3.9.5. Hyperlinked Identifiers

Referring to a Haskell identifier, whether it be a type, class, constructor, or function, is done by surrounding it with single quotes:

-- | This module defines the type 'T'.

If there is an entity T in scope in the current module, then the documentation will hyperlink the reference in the text to the definition of T (if the output format supports hyperlinking, of course; in a printed format it might instead insert a page reference to the definition).

It is also possible to refer to entities that are not in scope in the current module, by giving the full qualified name of the entity:

-- | The identifier 'M.T' is not in scope

If M.T is not otherwise in scope, then Haddock will simply emit a link pointing to the entity T exported from module M (without checking to see whether either M or M.T exist).

To make life easier for documentation writers, a quoted identifier is only interpreted as such if the quotes surround a lexically valid Haskell identifier. This means, for example, that it normally isn't necessary to escape the single quote when used as an apostrophe:

-- | I don't have to escape my apostrophes; great, isn't it?

For compatibility with other systems, the following alternative form of markup is accepted[3]: `T'.

3.9.6. Emphasis and Monospaced text

Emphasis may be added by surrounding text with /.../.

Monospaced (or typewriter) text is indicated by surrounding it with @...@. Other markup is valid inside a monospaced span: for example @'f' a b@ will hyperlink the identifier f inside the code fragment.

3.9.7. Linking to modules

Linking to a module is done by surrounding the module name with double quotes:

-- | This is a reference to the "Foo" module.

3.9.8. Itemized and Enumerated lists

A bulleted item is represented by preceding a paragraph with either “*” or “-”. A sequence of bulleted paragraphs is rendered as an itemized list in the generated documentation, eg.:

-- | This is a bulleted list:
--
--     * first item
--
--     * second item

An enumerated list is similar, except each paragraph must be preceded by either “(n)” or “n.” where n is any integer. e.g.

-- | This is an enumerated list:
--
--     (1) first item
--
--     2. second item

3.9.9. Definition lists

Definition lists are written as follows:

-- | This is a definition list:
--
--   [@foo@] The description of @foo@.
--
--   [@bar@] The description of @bar@.

To produce output something like this:

foo

The description of foo.

bar

The description of bar.

Each paragraph should be preceded by the “definition term” enclosed in square brackets. The square bracket characters have no special meaning outside the beginning of a definition paragraph. That is, if a paragraph begins with a [ character, then it is assumed to be a definition paragraph, and the next ] character found will close the definition term. Other markup operators may be used freely within the definition term.

3.9.10. URLs

A URL can be included in a documentation comment by surrounding it in angle brackets: <...>. If the output format supports it, the URL will be turned into a hyperlink when rendered.

3.9.11. Images

An image can be included in a documentation comment by putting its URL in double angle brackets: <<...>>. If the output format supports it, the image specified by the URL will be included in the rendered documentation at this point.

3.9.12. Anchors

Sometimes it is useful to be able to link to a point in the documentation which doesn't correspond to a particular entity. For that purpose, we allow anchors to be included in a documentation comment. The syntax is #label#, where label is the name of the anchor. An anchor is invisible in the generated documentation.

To link to an anchor from elsewhere, use the syntax "module#label" where module is the module name containing the anchor, and label is the anchor label. The module does not have to be local, it can be imported via an interface.



[3] We chose not to use this as the primary markup for identifiers because strictly speaking the ` character should not be used as a left quote, it is a grave accent.