I’ve always wished I could document my own code with Haddock even when it isn’t exported. Today I was exploring the Haddock code-base (which contains a fair number of Haddock-comments) and wanted an easier way to read it.

First I tried `cabal haddock –hyperlink-source`. It only documented Distribution.Haddock because that’s the only exported module of the library! `cabal haddock -v` told me that it was passing `–hide=all the other-modules` to haddock, which I couldn’t reverse with `cabal –haddock-option`. The only way to “fix” that was to hack haddock.cabal so that all modules appear under an `exported-modules:` clause (which is only allowed under `library`, not `executable`, so I had to spuriously merge the executable section into the library section). Yay! Then I had to remove Haddock.Types’s {-# OPTIONS_HADDOCK hide #-} which was causing a bit of trouble.

Adding –haddock-option=–ignore-all-exports includes non-exported functions in the documentation, which can be helpful or unhelpful. I wish it had a mode to include the un-exported stuff *after* all the exported stuff, with a clear separation. As a side note, –ignore-all-exports also “breaks” docs of Distribution.Haddock and any module that re-exports things from other modules, currently…

HsColour is pretty cool too, but it would be even cooler if it hyperlinked all the identifiers in the source, like Haddock does… hmm.

EDIT: I forgot to attach my actual silly patch to Haddock. Can’t find out how to get WordPress to let me upload it either. oh well, here it is: gee, I can’t even get it to turn into a link, here on Linux?: http://isaac.cedarswampstudios.org/2009/isaacs-silly-haddock-self-doc.dpatch

Share this: Twitter

Facebook

Like this: Like Loading... Related