On 14/08/2009 20:54, Duncan Coutts wrote:
On Thu, 2009-08-13 at 15:51 -0400, David Menendez wrote:
It would be nice if the packages in the Haskell Platform met some minimum standards for documentation.
Further on this topic...
I think it's a problem with many of our libs that while we have good enough reference documentation, there is often very little in the form of introductory documentation.
As you pointed out in the QC example, each function can be accurately documented without it giving any idea what some of the concepts mean or how to use the library.
I think partly this is that haddock is good at and encourages reference docs but not any other kind. It is possible to put introductory sections at the top of a module, they have to go in the export list. Without wanting to blow my own trumpet too much, with the docs for the 'tar' package I tried to give more introductory explanation and examples of how to use the api: http://hackage.haskell.org/packages/archive/tar/0.3.1.0/doc/html/Codec-Archi...
Also, I think the synopsis section becomes fairly useless for APIs that are bigger than about 10 items because it doesn't give any structure or indicate what is important and what is not. For larger multi-module packages there's also no obvious place to put introductory text. The user does not necessarily know which is the "main" module to look for it in.
I've wanted to get rid of the synopsis, or make it optional, or make it click-to-expand, or something else, for a long time. But I never managed to get around to it - perhaps a Hackathon project for someone? Cheers, Simon