Andy Gill wrote:
[snip]
> I've been playing will possible formats of such documentation.
> Have a look at http://www.cse.ogi.edu/~andy/gooddoc.htm
> for what I'm currently thinking of.
This is very much better than what we have already, but I'll make
the following quibbles anyway:
(1) it should be possible to view all the specifications for a module
in one big HTML page. (It looks like this one is meant to occupy
a page all to itself.) Otherwise it is tiresome searching to see
if the function I want is there.
(2) I think we can assume that the user who doesn't yet understand
laziness shouldn't be worried about it. On the other hand,
the user who does will probably assume anyway that where
it makes sense, the function will cope even in the presence of
undefined values. So get rid of mentions of infinite lists and
the second and third examples.
(3) The information "No filtering is done; every input appears as an
output" is also redundant. If there was filtering, you would
certainly say so, and even the naive would realise this.
In general you should try very hard to keep to one line of explanation
and one example, or if you absolutely have to, two lines and two
examples.
Here is my revised version of the documentation. Sorry I can't
manage the pretty formatting:
unzip :: [(a,b)] -> ([a],[b])
-----
Description:
unzip takes a list of pairs and returns a pair of lists.
Examples:
unzip [(1,2),(3,4),(5,6)] = ([1,3,5],[2,4,6])
Definition:
unzip = foldr (\(a,b) ~(as,bs) -> (a:as, b:bs)) ([],[])
See Also:
unzip3
