On Thu, Aug 13, 2009 at 4:35 PM, Don Stewart wrote:

dave:

...

It would be nice if the packages in the Haskell Platform met some minimum standards for documentation.

Shrinking is explained in the original QC papers -- it is a killer feature that we somehow lived without.

Are you referring to Section 5.4 of "QuickCheck: A Lightweight Tool for Random Testing of Haskell Programs" by Claessen and Hughes? That says that Andy Gill else implemented shrink (under a different name) in his version of QuickCheck and says that it returns "a list of smaller, but similar values to its argument -- for example, direct subtrees." Even if a Haskell Platform user was able to track down the original paper (published in 2000 and nowhere referenced in the QuickCheck documentation), and connect the "shrink" function to Gill's "smaller" function (text search won't help), all they would learn is that shrink returns values which are "smaller" and "similar" to the argument. I think we can do better than that. Here's another question, what's the motivation for (><) in QuickCheck 2? If you look at the instance for (,) in QuickCheck 1.2, you see coarbitrary (a, b) = coarbitrary a . coarbitrary b but in QuickCheck 2.1 it's coarbitrary (x,y) = coarbitrary x >< coarbitrary y I'm sure there's a good reason for that, but as far as I can tell it isn't stated anywhere.

That said, we need an analysis of the missing pieces for our existing libraries to meet standard.

Agreed. -- Dave Menendez http://www.eyrie.org/~zednenem/

On Fri, 2009-08-14 at 16:46 +0100, Neil Mitchell wrote:

Hi

...

...

...

It would be nice if the packages in the Haskell Platform met some minimum standards for documentation.

Shrinking is explained in the original QC papers -- it is a killer feature that we somehow lived without.

QuickCheck 2 is an amazing piece of work. My experience is that it finds bugs in properties that QuickCheck could never find counter-examples for. Shrinking is also fantastic. However, the change from QuickCheck 1.x to QuickCheck 2.x is a big one - it's probably of the same magnitude as haskell-src to haskell-src-exts, just with a coincidence of using the same package name. At the same time I couldn't figure out how to QuickCheck IO properties so just used unsafePerformIO - I think the pieces are there but the documentation isn't.

I'm not sure if QuickCheck 2 is right to go in the HP at this particular moment - but I know I'm never using QuickCheck 1 again.

Yes, it is a significant update. That's why we're asking people to think about it and decide if they want it updated now or later. My personal opinion is that QC2 is great and we should update to it now. Duncan

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. Duncan

I like the format where haddock has reference, and then the main module's synopsis has links to external documentation like papers and tutorials. A warning if the paper's terminology differs from the implementation would be nice! As for what the "main module" is, I would put everything in the package within a single root module and then put the links to learning material in the root module's synopsis, even if the root doesn't doesn't contain anything else, or is just re-exports. On the subject of quickcheck 2, the main page (which is http://www.cs.chalmers.se/~rjmh/QuickCheck/ according to hackage) doesn't give any indication that there are two versions, doesn't say to which version the docs apply to, doesn't have any release information, "current developments" doesn't look very current, and doesn't have any dates anyway. So I had no idea there were two versions, or that the newer version was better. Yeah, I'm basically echoing David, but my experience was the same.

On Mon, Aug 17, 2009 at 4:45 PM, Simon Marlow wrote:

...

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?

Me too. I've also been thinking about having Haddock output more semantically correct HTML to cut down on the document size and make it easier to change the CSS styling. There's an open bug about the issue in the Haddock trac: http://trac.haskell.org/haddock/ticket/108 Perhaps the whole HTML output module could be overhauled to make it easier to experiment with. Do we have a good HTML combinator library that we could use to generate the output? Cheers, Johan