Re: Haskell Wish list: library documentation

[S. Alexander Jacobson]

If you have some type of generic programming interface, then unzip changes
too.  Unzip gets generalized from working only with lists to working with
any recursive data structure (see http://www.cs.chalmers.se/~patrikj/poly/).

I agree that we will have some version of unzip either way, I am just not
sure what implementation we claim and whether the description/definition 
should be in terms of lists or in terms of generic recursive
datastructures (lists, trees, snocs, etc).  

-Alex-

___________________________________________________________________
S. Alexander Jacobson                   Shop.Com
1-212-697-0184 voice                    The Easiest Way To Shop


On Wed, 8 Sep 1999, Michael Hobbs wrote:

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