[Haskell-cafe] Literate Haskell

[Jérémy Bobbio]

On Saturday 19 February 2005 01:38, Mark Carroll wrote:
> On Fri, 18 Feb 2005, Dmitri Pissarenko wrote:
> > It seems to me like a good idea, since during coding it often helps
> > to write down one's thoughts (often, I find a solution to a
> > complicated problem in this way).
> >
> > What are your experiences with using literate Haskell?
>
> I used to use it - I also like to note things in among the code.
> Now I tend to use Haddock documentation more.

From my point of view, there is two different questions that some 
documentation might answer:
  
  "How does this work?"

This documentation should describe the implementation design, issues, 
tricks, etc.  I think that Literate Haskell is well suited to write 
documentation answering this question.  By printing and reading a whole 
module, it is easy to follow the implementor thoughts. 

  "How should I use this?"

This documentation should describe how to use a module (let's say "its 
API") without understanding more than needed how it works under the 
hood.  It should be indexed and hyperlinked when one needs to quickly 
lookup the behaviour for some function.  Haddock was designed to write 
this kind of documentation.

I really see Literate Haskell and Haddock as two orthogonal tools, and 
that help me to focus when writing docs.

Cheers,
Jérémy.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://www.haskell.org//pipermail/haskell-cafe/attachments/20050221/0c55a013/attachment.bin