The debate about library documentation has been illuminating indeed.
I have observed the following:
* There have been lots of messages --- more so than most topics that
appear on the list. Obviously there is lots of interest; the topic
seems be one with which most people have encountered problems in
the past so are keen to do something about.
* There is a large range of ideas.
* How difficult it is to ``get it right'' --
consider the amount of discussion about just one function unzip!
Even down to how lists should be displayed and whether an
example should use
unzip [("a", 1), ("b", 2), ("c", 3)] or
unzip [("", 1), ("a", 2), ("aa", 3)] or
unzip [("b", 9), ("m", 2), ("d", 3)] or ...
* Unanimous agreement about importance. No one has decried the need
for better documentation.
How to proceed? I believe that we should we should
1) decide upon some documentation scheme/format (what content to produce)
4) decide upon presentation schemes (how to display documentation)
2) decide which prelude/libraries to document (H98?)
3) organise contributions and create a review mechanism
My suggestion would be to provide extensive documentation for each
function in the prelude and libraries, but to do in such a way that many
possible ``views'' could be _automatically_ produced.
Here is a selection of views:
1) super brief: name, type signature, one line description
unzip :: [(a,b)] -> ([a],[b])
unzip takes a list of pairs and returns a pair of lists.
2) brief: like George Russell's example
> 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
3) verbose
This would have a similar structure to (2) but would include more
readable descriptions written with the inexperienced programmer in mind.
Also included could be (among possibly other items)
* test cases
* example reduction sequences
* more extensive examples --- even small segments of code to
demonstrate common idioms involving this function.
Obviously this documentation is somewhat open ended, and the amount
produced would depend upon the function, and the energy of the writer.
Orthoganal to these views of documentation is the media of presentation.
I suggest that different users would prefer one or more of the following
incomplete list:
* a single (say) Latex/Postscript document
* a single HTML document
* a sequence of HTML documents; perhaps grouping by similar function.
So we could produce for instance a compact printable ``quick reference''
form or extensive cross linked HTML form.
Regards
Richard
