[Haskell-cafe] Re: Literate Haskell

[Peter Simons]

Dmitri Pissarenko writes:

 > I'm curious what experienced Haskellers think about using
 > literate Haskell in daily work.

My experience is that literate-style documentation tends to be
out-of-sync or misleading as quickly as any other kind of
documentation. It doesn't matter that much whether you write

 | This function does something.
 |
 | > the_function ...

or whether you write (for Haddock):

 | -- |This function does something.
 |
 | the_function ...

It's just a difference in syntax.

I've also found that many of the projects I have seen actually
written in literate-style did *not* come with a particularly
good documentation. (Darcs probably is the exception; because
it is documented very well.)

I use literate Haskell mostly when writing articles that
include code. For that, it is great. But for everyday
programming, I prefer Haddock.

Peter