> 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 _______________________________________________ Haskell mailing list [EMAIL PROTECTED] http://www.haskell.org/mailman/listinfo/haskell
