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