Writing IDoc-enabled Haskell modules

IDoc requires Haskell modules to follow a handful of simple conventions including markers at comment blocks that contain interface documentation as well as rules for formatting lists and so on.

Formatting of top-level declarations

All delarations relevant for interface documentation processing need to follow the Haskell layout rules (i.e., they may not use explicit braces). Moreover, the head of instance, default, data, and class declarations must be in its entirety on a single line.

Interface comments

Interface comments are comments that the programmer wishes to appear in the interface documentation generated by IDoc. All interface comments must start in the leftmost column and must use the single line comment syntax. The first line of an interface comment block must start with the character sequence -- | or -- /. All following single line comments starting in the leftmost column up to the first non-comment line are regarded as part of this interface comment block. There are three types of interface comments:

1. Module comments: These are all interface comments that precede the module header (i.e., the keyword module).
2. Free standing interface comments: These are all interface comments that are not directly associated with a single toplevel declaration. A free standing comment block is followed by an empty line, an indented comment, or a comment in nested comment syntax.
3. Declaration comments: These are associated with a single toplevel declaration and must immediately precede the declaration (there may not be an empty line between a declaration comment and it's associated declaration). We call such declaration, interface declarations. IDoc copies interface declarations in to the generated interface documentation.

The difference between the interface comment markers -- | and -- / is relevant only for declaration comments. In the latter case, the declaration is assumed to be exported abstractly (i.e., without any associated definition).

If the lexeme -- introducing a comment is immediately (i.e., without any white space inbetween) followed by one or more dash characters '-', these dash characters are converted to white space.

Interface declarations

An interface declarations is assumed to continue up to the next line that either contains white space only or contains code or a comment starting in the leftmost column. Note that this corresponds to what Haskell's layout rule requires.

If to the right of the lines of an interface declaration, there are single-line comments, they are assumed to be descriptions of the corresponding pieces of the declaration.

In the body of a class definition and the right hand-side of data declarations, the rules for commenting methods and constructors, respectively, are the same after shifting the body of the declaration as many columns to the left as the body is indented. The only exception is that in a data declaration, constructor declarations following an interface comment and start with "= " or "| " may start two columns further to the left than the interface comment.

On the top-level only interface declarations are taken into account. In local scopes (class and data declarations) all local entities are collected if the containing declaration is not exported abstractly. However, if the containing declaration is exported abstractly, only the local entities preceded by an interface comment appear in the documentation.

Comment formatting

In an interface comment, the following formatting conventions apply:

• In the first line of the first comment block of a module, if the string -*-haskell-*- appears, it is removed.
• Empty lines separating two non-empty blocks introduce a paragraph break.
• Phrases enclosed in `...' or @...@ are set verbatim in a fixed-width font.
• Headings: Comments of the form

  -- |Heading
  -- --------

  as well as those of the form

  -- Heading ----

  (four or more dashes at the end of the line)

  are set as section headers and comments of the form

  -- |Heading
  -- -

  are set as subsection headers.

• Displays:
  • Stared and dashed lists are set as itemisation lists.
  • Numbered lists (with numbers in parenthesis) are set as numbered lists.
  • Indented text is rendered as a quote.
  • Bird-tracked text is rendered as a verbatim code display. (Each line in the paragraph needs to have a '>' symbol and in each line the '>' must be followed by a space character.)

  Each display must be in a separated paragraph (i.e., it must be preceded and followed by an empty line if it is not the start or end of a comment block). In the case of lists, the list items need to be separate paragraphs. Paragraphs following a list item that are further indented than the item are regarded to be part of that item.

• Everything else is set as vanilla text.