Haddock, .lhs, and GHC
richardg at richardg.name
Sun Jun 15 00:20:01 EDT 2008
I did a little digging on this issue and didn't find a definitive answer.
According to the Haddock page in the wiki, Haddock is the de facto way
of documenting files [http://haskell.org/haskellwiki/Haddock].
Does this mean that literate source files should be discouraged? They
seem to be fairly common, especially in conjunction with Cabal (i.e.,
Setup.lhs). They also appear in quite a few beginner tutorials, which
can send new users down the wrong path (e.g.,
Is there an effort and/or intent to move the GHC sources away from .lhs
The reason I ask is:
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?
I get the feeling that HUnit isn't getting much attention. Is that
because it's "done" or because it's obsolete and will soon be removed?
More information about the Glasgow-haskell-users