haddock (and -- $)

[Simon Marlow]

> hello. a few comments and questions on haddock 
> (www.haskell.org/haddock/)
> 
> 1. haddock is great

Thanks ;)

> 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:

   $ haddock
--read-interface=file:///usr/share/ghc-6.2/html/libraries/base,/usr/shar
e/ghc-6.2/html/libraries/base/base.haddock

or you can point to the online docs, by replacing the first URL with
http://www.haskell.org/ghc/docs/6.2/html/libraries/base.

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.

Cheers,
	Simon