Standard module header trivia

[Simon Marlow]

> > I'm personally not very fond of the literate style, so=20
> 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,=20
> it expects
> > all the documentation to be in comments in the Haskell source, which
> > leaves little reason to use literate comments.
>=20
> As I recall, we once had a discussion here about program=20
> documentation in
> which we (well, only some of us apparently :) concluded that=20
> literate comments
> were good for documenting a module's implementation, but=20
> something else was
> needed for documenting the client interface. And that led you=20
> eventually to develop Haddock...
>
> So I guess you are saying that in fact Haddock is suitable=20
> for documenting the
> implementation as well as the interface. Is that right? OK, I=20
> 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