Haddock, .lhs, and GHC

[Richard Giraud]

Hello

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., 
http://haskell.org/haskellwiki/How_to_write_a_Haskell_program).

Is there an effort and/or intent to move the GHC sources away from .lhs 
entirely?

---

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?

Thanks,

Richard G.