Changes between Initial Version and Version 1 of HaddockNotes


Ignore:
Timestamp:
Jul 20, 2008 10:46:34 PM (11 years ago)
Author:
nominolo
Comment:

Created page. Documents some issues+workarounds for Haddock.

Legend:

Unmodified
Added
Removed
Modified
  • HaddockNotes

    v1 v1  
     1= Notes for using Haddock (for GHC) =
     2
     3Some comments use different "markup" than Haddock.  Consult the [[http://www.haskell.org/haddock/doc/html/ch03s08.html][Haddock Markup Rules]].
     4
     5== Haddock Pitfalls ==
     6
     7Haddock is not very forgiving, so the following is a list of issues and suggested workarounds.  Items in '''bold''' are problems where the '''error location does not show the actual problem''' and are thus hard to spot. 
     8
     9Note: All problems below were encountered with Haddock 0.9, different versions may behave differently.
     10
     11 * '''Trailing {{{where}}} clause'''.  If a function ends with an empty {{{where}}} clause, Haddock will consider all remaining functions (regardless of indentation level) as local functions.  If you're lucky it fails at the next {{{type}}} or {{{data}}} declaration, if you're not lucky, the remaining functions will probably be silently ignored.  So, be careful!
     12
     13 * '''Bullet lists ({{{*}}}) in module head'''.  If your module description contains not properly indented bullet lists, Haddock will fail with a parse error at the {{{module Foo}}} part.  The workaround is to use {{{-}}} instead of {{{*}}}.
     14
     15 * '''Trailing semicolon in {{{case}}} expression'''.  Given the following code
     16{{{
     17do { foo <- calcSomeFoo
     18   ; case foo of
     19       Xxx -> blahBlah ;  -- <-- HERE
     20       Yyy -> ueouoe
     21   }
     22}}}
     23   Haddock will choke after the {{{Yyy}}} constructor.  The problem is the trailing semicolon in the previous line.
     24
     25 * '''{{{do}}} with bracket on next line'''.  In the following code
     26{{{
     27  blah foo $ do
     28  { blah blub
     29  ; ...
     30  }
     31}}}
     32   Haddock does not know that the opening brace belongs to the {{{do}}}.  Move it after the {{{do}}} and you're fine.
     33
     34 * '''{{{\end{code}}}} with trailing whitespace'''.  This will fail somewhere trying to parse the documentation.
     35
     36 * Emphasis markers look like markup.  If a word is emphasised using the common {{{*important*}}} meme, Haddock gets confused when such a word appears at the beginning of a comment line.  If you want to convert the comment to Haddock markup you can use haddocks emphasising mechanism {{{/important/}}}.  If it should remain a comment, you can use underscores {{{_important_}}}.
     37
     38 * Constructors with multiple unnamed arguments.  Haddock doe not understand the following
     39{{{
     40data Foo = A    -- ^ describe constructor
     41            Arg1 -- ^ describe first argument
     42            Arg2 -- ^ and this
     43}}}
     44   The workarounds are to use named fields or to refer to arguments by number like this:
     45{{{
     46data Foo = A Arg1 Arg2
     47             -- ^ describe constructor.  Parameters:
     48             --
     49             --   1. describe first argument
     50             --
     51             --   2. describe second argument
     52}}}
     53   Note that the newlines are mandatory, otherwise the list will be inline which is a lot harder to read.
     54
     55 * Tuple components.  As above, you cannot document of a function parameter/result.
     56
     57 * Preprocessor macros.  Some preprocessor macros do not expand to something Haddock can parse. 
     58   You can define simpler substitutions by testing the {{{__HADDOCK__}}} variable:
     59{{{
     60#ifndef __HADDOCK__
     61... default definition ...
     62#else
     63... simplified definition ...
     64#endif
     65}}}