Re: Haskell Wish list: library documentation

[S. Alexander Jacobson]

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