restarting the discussion

[malcolm-hs@cs.york.ac.uk]

Hello to everyone who has joined the HaskellDoc mailing list.  We had
a little bit of discussion before announcing the list more widely,
but everything now seems to have stopped dead.  So it's time to get
thoughts rolling again.  Do check the list archive on haskell.org
to see what has already happened.

I'll start by declaring my interest in automatic documentation.
I have a proposal (not yet published, sorry, but coming soon) to
help organise the Haskell libraries, standard and non-standard.
But libraries are no good if you don't know what they contain.
Not everyone is either willing or capable to write high-quality
documentation for their libraries.  Hence, a tool which automatically
derives some kind of documentation directly from the source code would
be extremely useful as a starting point for exploring a new library.

When I first saw Armin Groesslinger's HDoc, I got very excited
because it generates very useful summary information about a library,
without the programmer having to add a single annotation whatsoever.
Or at least that's how it appears at first glance.

My immediate aim is to have a tool that produces browsable
documentation to be read by the user of a module, not necessarily
an author or developer (i.e. external docs, not internal docs).

Ideally, I want to see
    * what useful datatypes are exported;
    * the type signature of every exported function;
    * some textual description of each datatype;
    * some textual description of each exported function;

Now obviously if (as all good programmers do :-) there are type
signatures in the source code, it is relatively easy to extract them
with a tool.  Textual descriptions can also be extracted from the
programmer's comments.

But the programmer will write many kinds of comment - not all are
intended for users - many describe the implementation, which is of
no interest to the mere user.  So we need to distinguish different
styles of comments.  This can be done lexically or positionally,
and we need to agree a standard.

I have another big requirement.  The source code must remain readable
as source code.  I absolutely loathe so-called "literate programming"
style, because it breaks this rule horribly.  From my point of view,
any new documentation standard must be as non-intrusive as possible.
This almost immediately rules out XML-style tags I'm afraid.  Other
(less heavy) lexical conventions might be OK though, provided there
are only a small number of them to be learnt.

I am intrigued by the use of positional cues (e.g. a comment just
before or just after a type signature) as a clever way of associating
documentation with code, whilst avoiding extra syntax.

For those who have not yet looked at Armin's HDoc, can I encourage you
to do so, as a concrete example of how some of these ideas have been
put into practice.  He develops a "special" kind of comment, introduced
by {--- rather than {-, and has some small lexical conventions that
help to generate nice hyperlinked HTML.

Also, look at Jan Skibinski's tool which captures comments by their
position with respect to a signature.  Both are linked from the
haskell.org page on libraries and tools.

Regards,
    Malcolm