3.8. Markup

Haddock understands certain textual queues inside documentation annotations that tell it how to render the documentation. The queues (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.8.1. Paragraphs

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

3.8.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.8.3. Code Blocks

Displayed blocks of code are indicated by surrounding a paragraph with @...@ or by preceding each line of a paragraph with >. For example:

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

3.8.4. 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).

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

3.8.5. 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.8.6. 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.8.7. 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.8.8. 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.

Notes

[1]

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.