...

I'm personally not very fond of the literate style, so that's why none of the existing hierarchical libraries are literate (I actually converted several of them from .lhs into .hs). One reason is that Haddock doesn't understand literate scripts - or at least, it expects all the documentation to be in comments in the Haskell source, which leaves little reason to use literate comments.

As I recall, we once had a discussion here about program documentation in which we (well, only some of us apparently :) concluded that literate comments were good for documenting a module's implementation, but something else was needed for documenting the client interface. And that led you eventually to develop Haddock...

So I guess you are saying that in fact Haddock is suitable for documenting the implementation as well as the interface. Is that right? OK, I didn't know that; I will have to take a closer look at it.

Not really - Haddock is intended as an interface documenting tool only. But there might be scope for extending it to support inplementation docs too, or extending Haddock to pick out annotations from literate comments somehow. I imagine there would be some overlap between the implementation and the interface docs, so that using completely separate documentation formats might be cumbersome. Cheers, Simon