Changes between Initial Version and Version 1 of HaddockNotes

Jul 20, 2008 10:46:34 PM (11 years ago)

Created page. Documents some issues+workarounds for Haddock.


  • HaddockNotes

    v1 v1  
     1= Notes for using Haddock (for GHC) =
     3Some comments use different "markup" than Haddock.  Consult the [[][Haddock Markup Rules]].
     5== Haddock Pitfalls ==
     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. 
     9Note: All problems below were encountered with Haddock 0.9, different versions may behave differently.
     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!
     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 {{{*}}}.
     15 * '''Trailing semicolon in {{{case}}} expression'''.  Given the following code
     17do { foo <- calcSomeFoo
     18   ; case foo of
     19       Xxx -> blahBlah ;  -- <-- HERE
     20       Yyy -> ueouoe
     21   }
     23   Haddock will choke after the {{{Yyy}}} constructor.  The problem is the trailing semicolon in the previous line.
     25 * '''{{{do}}} with bracket on next line'''.  In the following code
     27  blah foo $ do
     28  { blah blub
     29  ; ...
     30  }
     32   Haddock does not know that the opening brace belongs to the {{{do}}}.  Move it after the {{{do}}} and you're fine.
     34 * '''{{{\end{code}}}} with trailing whitespace'''.  This will fail somewhere trying to parse the documentation.
     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_}}}.
     38 * Constructors with multiple unnamed arguments.  Haddock doe not understand the following
     40data Foo = A    -- ^ describe constructor
     41            Arg1 -- ^ describe first argument
     42            Arg2 -- ^ and this
     44   The workarounds are to use named fields or to refer to arguments by number like this:
     46data Foo = A Arg1 Arg2
     47             -- ^ describe constructor.  Parameters:
     48             --
     49             --   1. describe first argument
     50             --
     51             --   2. describe second argument
     53   Note that the newlines are mandatory, otherwise the list will be inline which is a lot harder to read.
     55 * Tuple components.  As above, you cannot document of a function parameter/result.
     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:
     60#ifndef __HADDOCK__
     61... default definition ...
     63... simplified definition ...