Haddock, .lhs, and GHC

[Duncan Coutts]

On Sat, 2008-06-14 at 22:20 -0600, Richard Giraud wrote:

> I'm looking at the Test.HUnit modules and there are no Haddock 
> annotations.  I thought I'd help document the modules but, when I had a 
> look at the source files, I found they were .lhs instead of .hs.  There 
> is already some documentation in the files but it's not visible to Haddock.
> 
> What's the best way to proceed in a case like this?
> 1. Shoe-horn in the Haddock annotations by putting them in the code 
> sections (e.g., > -- | Document comment...) but this seems a little 
> cumbersome, especially if these comments show up in the published form 
> of the .lhs file.
> 
> 2. Rename to the files to .hs and touch up the files so they compile, 
> then add the Haddock annotations.
> 
> 3. Another option?

You can use:

| blah blah

> ordinary code

And if you're using Cabal then it uses an extended 'unlit' function
which generates sensible input for haddock. In fact this only works at
the moment with haddock-0.x (ie 0.8, 0.9) because haddock-2.x does it's
own unliting.

For an example of this lhs/haddock style, see takusen.

Duncan