Josef Sveningsson wrote:
>
> Maybe the definition of a function should be left out from the
> documentation, at least by default. Javadoc has a number of options so
> that one can choose how much information the documentation should contain.
> If we have a good specification and a set of axioms and rules, that's all
> we need. Taking javadoc as an example again, imagine how it would look if
> it included the definition of every function (yes, I know it's not really
> comparable :-).
Sometimes (like unzip) the definition is just one line, so might
be worth including. Have a look at the crib sheet at
the back of Bird and Wadler for examples of documentation
like this, with short definitions. Perhaps more than half the
Prelude falls into this camp.
Many Haskell functions, however, would be to long to include
in the documentation.
I'd expect the following structure of a generated
Haskelldoc webpage.
(1) First, a high level view of the module;
what types are defined, what top level (exported?)
functions are there, what classes are defined, etc.
(2) Then more detail on each of the above.
- Perhaps the type, the purpose and the description?
If we follow the javadoc lead, then (1) and (2) would be
in the same page.
(3) For each function, class, method, type, etc.,
there would be an individual page, with details,
including examples.
Of course, hot links could interconnect these pages.
One reason for the wording "module Prelude" in
the top right of the webpage example was to be
a hot link back to the modules own web page.
One more thing I'd like to see is a way of combining
documentation for similar definitions. For example
type Color = String
black = "BLACK"
white = "WHITE"
red = "RED"
It would be nicer to have one page for black, white and red,
rather than individual entries.
Andy
