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.