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