How To Navigate Your Code:

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

About these ads

5 Responses to “How To Navigate Your Code:”

  1. haddock2009 Says:

    P.S.
    1. how do I quote literal text in WordPress (so it doesn’t turn dash-dash into long dash, for example)?

    2. Of course ignore-exports is quite faithful to what it claims to do (matching the Haskell98 effect of omitting the export list), but I was pleasantly surprised to find a feature that did even something vaguely like what I wanted

    3. This is increasing my code-reading/comprehension speed tenfold, I wish I’d thought of it earlier

  2. Andrea Vezzosi Says:

    have you seen the –internal and –executables options? with them you shouldn’t need to mangle the .cabal file

  3. haddock2009 Says:

    Andrea: Interesting! –internal has the same problems as ignore-exports (of course, because it uses that feature). –executables *only* documents the executable and I don’t see how to make it document the library too? (there’s both an executable and a library in haddock.cabal). I’m using:

    > cabal –version

    cabal-install version 0.6.2

    using version 1.6.0.3 of the Cabal library

  4. Andrea Vezzosi Says:

    It creates separate documentations for the library and the executables, e.g one at dist/doc/html/haddock/index.html and the other at dist/doc/html/haddock/haddock/index.html.
    Maybe that’s not the best outcome and we should create an aggregate index?

  5. Magnus Says:

    I believe you can use some HTML tags in the text, so, maybe <verbatim> would work for your double-dashes?

    Otherwise I can recommend the markup plugin.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


Follow

Get every new post delivered to your Inbox.

%d bloggers like this: