proposal for updates in next major HP release

[Simon Marlow]

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-Archive-Tar.html
>
> 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