haddock (and -- $)
simonmar at microsoft.com
Thu Dec 18 11:11:40 EST 2003
> hello. a few comments and questions on haddock
> 1. haddock is great
> 2. haddock's interpretation of "-- $" is un-great:
> I have two types of "-- $" occurences in my code
> that conflict with haddock's idea of "named doc chunks"
> a. CVS macros: -- $Id: ...$
> b. pipes like this, with some lines commented out:
> let x = this_function
> $ that_function
> -- $ but_not_this
> $ arg
I'm not sure that we can/should do anything about this. The same
problem crops up with '-- |' too: you might comment out some guards for
example. The solution is to add an extra space after the '--', or use
three dashes '---', etc. etc.
> 3. how can I refer to external system libraries documentation
> (i. e. Data.FiniteMap from the ghc web site)?
Download a GHC distribution, which has the .haddock files for the
libraries. Then use the --read-interface option, something like this:
or you can point to the online docs, by replacing the first URL with
You can add further --read-interface options for the other packages that
come with GHC.
In the future, Haddock will make this easier by asking GHC where it
keeps its documentation.
> 4. haddock does not seem to understand cpp #ifdefs.
> how can I work around this? (I know I shouldn't use cpp
> in the first place, but I want to document existing code,
> and not rewrite it just to make the doc tool happy :-)
You can run cpp over the source file before feeding it to Haddock. This
is what we do for GHC's libraries. eg.
$ ghc -E -cpp Foo.hs -o Foo.raw-hs
$ haddock Foo.raw-hs ...
You can use some appropriate Makefile rules to automate this.
More information about the Haskell