I think I might be able to clarify George's point with an example:
unzip. Presumably, the unzip function will stay, no matter what happens
with existential types, arrows, etc. The problem is, I don't know what
unzip *does*. (Actually, I do, but I'm taking the POV of a novice here.)
The only documentation for unzip is this:
unzip = foldr (\(a,b) ~(as,bs) -> (a:as,b:bs)) ([],[])
Not exactly intuitive. Could be better. I'm assuming that George's point
is that this documentation leaves plenty of room for expansion.
- Michael Hobbs
"S. Alexander Jacobson" wrote:
>
> Are we talking about documentation for the H98 libraries?
> Are these libraries relevant? Don't MPTC, Existential Types, Restricted
> Type Synonyms, Arrows, and an FFI substantial change the architecture,
> interface, and implementation of the libraries? As these language
> features are becoming more accepted (implemented in GHC & Hugs), is it
> worth investing time in supporting what are in fact really strange library
> APIs.
>
> For example, if you assume something simple, like the ability to talk to
> Java classes in some reasonably lightweight manner, then you could replace
> the wierdness of the Haskell directory module with a wrapper around
> the JNDI API.
> Whatever happened to the arrows proposal? Whatever happened to the
> categorical prelude?
>
> Is there some state of play document that covers discussion about these
> issues? At very least, can someone provide some story about what belongs
> in the libraries and what should be left out at this stage of the game?
>
> -Alex-
> ___________________________________________________________________
> S. Alexander Jacobson Shop.Com
> 1-212-697-0184 voice The Easiest Way To Shop
>
> On Wed, 8 Sep 1999, George Russell wrote:
>
> > Don't add more functions like concatSep to the standard library or prelude.
>Instead document
> > what is there better. I found it far easier to find functions in the Standard ML
>Basis
> > library than in the Haskell standard. Here are some suggestions for what could be
>done:
> > (1) document the IO functions in one place, so I don't have to search both Report
>and
> > the Library Report. Ditto for other modules. I suggest that all the function
> > specifications be in the Library Report. The information about which functions
> > are available in the prelude should be given in both the function description
>in
> > the Library Report, and in the description of the prelude in the Report
> > (which could say, all modules are implicitly preceded by the following imports:
> > import IO(putStr,...), or some such text).
> > (2) document all functions with some text, or at least an example. Currently many
>functions
> > are documented only by their implementation (which, as we have seen on the
>Haskell
> > mailing list, is sometimes actually buggy), and others are not documented at
>all.
> > I recommend the style of the Haskell Report which includes a great deal of
> > helpful commentary along with the definitions.
> > (3) there should be an index of all functions, linked via page numbers/HTML links
>to
> > the actual definitions.
> > (4) Haskell implementors should be encouraged to modify the library report by
>adding
> > their own functions and comments directly into the main text. These should of
> > course be clearly marked in a standard way, EG using the HTML emphasis tag
> > (which I forget the name of but which I think normally produces italics).
>Also the
> > title page of the library report thus modified should indicate that it is not
> > the vanilla version but modified for GHC 4.04 (or whatever).
> >
