-- * =head2 -- ** =head3 -- *** =over, =back Nothing =item * * or - at start of paragraph =item 1. (1) or 1. at start of paragraph =item name [@name@] at start of paragraph

--| Documentation for the next thing (top level or in declarations) {-| Multiline version of above -}

--^ Documentation for the previous thing (top level or in declarations) {-^ Multiline version of above -}

Documentation Build Process ===========================

make haddock

This produces the cross-linked html documentation for Pugs in the ./dist/doc/html directory. If any of the input .hs files is causes haddock to fail then the haddock-broken make target can be used to produce documentation for one file at a time. This is inferior to make haddock as the identifier links aren't correctly produced.

Internally, make haddock first filters the .hs files to remove problematic constructs. The haddock program can be confused by some GHC extensions and the util/munge_haddock.pl attempts to avoid this.

Note that Haddock only builds documentation for the interface of modules, so the documentation for internal methods may not appear in the output. The --# ignore-exports (or {-# ignore-exports}) option can appear for the module definition to override this.

Understanding and Correcting Errors ===================================

If make haddock fails then you can use make haddock-broken to produce inferior documentation. There are a few strategies available to fix the file which breaks haddock. Note that the location of the error messages are not always helpful, for example, a "string" pages above can cause an error at the first line of code below it.

As haddock ignore plain {- -} comments, you can just change the "{-|" to test whether a particular comment block is causing the problem.

Once the block has been found, it can be split with "-}{-" to binary search for the problem. Turning a paragraph into a verbatim block with s/^/> / can also isolate the trouble. Individual files can be run with haddock $filename.

Common problems: - @Larry unescaped @ characters - "double-quoted strings" which are not links to modules - -- | ControlEnv !Env, misinterpreted commenting out (-- \| instead)

To fix problems you can escape with \, rephrase or use a non-haddock comment block.

If the code is the source of the problem then the following #ifdefs can be used to remove the code before haddock sees it. This is done in munge_haddock.pl

#ifndef HADDOCK #endif HADDOCK

Haddock Vim Syntax File =================

Ask bsb on #perl6 if you want to take it for a spin