Using Haddock for standard libraries (was: RE: ANNOUNCE: Haddock version 0.1, a Haskell documentation tool)

[Simon Marlow]

[ redirected to libraries@haskell.org ]

> At 2002-05-01 04:48, Simon Marlow wrote:
>=20
> >I'm pleased to announce version 0.1 of Haddock, a documentation
> >generation tool for Haskell source code.
>=20
> I take it this is the "standard" Haskell documentation tool now, that=20
> implementations of the standard libraries will use? I've been=20
> waiting for something like this.

I'd like Haddock to become a widely-used Haskell documentation tool, but
I don't want to presume to call it "the standard tool".

I'd like us to use Haddock to document the hierarchical libraries in
fptools/libraries (indeed, that was the main reason I wrote it).
Haddock is by no means perfect, but I think it's a step in the right
direction.  What do other people think?  Should we adopt Haddock as the
tool for documenting the libraries?

This doesn't mean it will be a "standard" as such, merely that the
reference implementation of the libraries will be marked-up using
Haddock annotations.  If people aren't comfortable with requiring a
specific tool for generating the documentation from the reference
sources, then we could perhaps standardise the annotation syntax
instead.

Nevertheless, we do *need* to document fptools/libraries in order that
we (the GHC team) can release the next version of GHC.  So excessive
faffing around is not an option :-) =20

Assuming that we adopt Haddock, I'd be grateful for any volunteers to
help document everything in fptools/libraries - including the Prelude
and Haskell 98 standard libraries (one of the shortcomings of our
current library documentation is that one has to go elsewhere to find
the documentation for these standard bits).  Prelude & std library
documentation can for the most part be culled from the Reports and
various other resources on the web, and much of the other library
documentation can be ported from the old hslibs documentation, suitably
unDocBooked.  I'll volunteer to coordinate the documentation effort.

Cheers,
	Simon