[Haskell-cafe] Literate Haskell
jeremy.bobbio at etu.upmc.fr
Mon Feb 21 14:37:45 EST 2005
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.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 189 bytes
Desc: not available
Url : http://www.haskell.org//pipermail/haskell-cafe/attachments/20050221/0c55a013/attachment.bin
More information about the Haskell-Cafe