proposal for updates in next major HP release
marlowsd at gmail.com
Mon Aug 17 10:45:51 EDT 2009
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:
> 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
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?
More information about the Haskell-platform