
On Thu, 8 Feb 2001 malcolm-hs@cs.york.ac.uk wrote: ....
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).
A good tool can produce either thing equally well. See below. ....
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.
My opinion is that there should be only one style of comment, the good and important comments. They can, of course belong to different entities, such as functions, classes, methods, datatypes, but all of them should be Good. If an entity is implementation specific then do not export it. But if you wish to make some special implementation notes in the exported entity then make them somewhere in the body of your code, not around the entity header, so the comment extractor will never touch it. But if you do write the comment around the header then be prepared to see it in documentation. The pressure is on you to do it right. You should be able to guarantee readability of the resulting interface.
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.
So you, Henrik and I agree on this point. I have been advocating it quite strongly right here. (BTW, I do write a lot of HTML-based "literate" tutorials but they are not meant as libraries. Libraries should be readable and easy to maintain).
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.
I have been working very hard to provide some working examples of interfaces that have all of the above features outlined by you. I was hoping that they will help with this discussion. However, few cared to check them out, which disappoints me greatly. In addition, those who have tried must have misunderstood my links since the have not found any of the samples - which is shown in the logs of my website. So here is the careful explanation of those links, or rather the links to new and improved interface samples. ------------------------------------------------------ They are in a temporary location and they may be removed one day. I do not wish them to be indexed from this email message, therefore I provide the information in two stages: 1. The directory is http://www.numeric-quest.com/haskell/ This directory is already indexed, which should be. 2. Append to the above one of the following filenames: Extractor.short.html Extractor.long.html InterfacePrinter.short.html InterfacePrinter.long.html That's all. ----------------------------------------------------- Now, here is some explanation. They are the actual interfaces to a tool I am working on. The tool reads Haskell source code, extracts structure of a module (this is done by module Extractor) and then prints the interface (done by InterfacePrinter) in one of two formats (so far): Ascii or HTML. All the above samples are HTML-"preformatted". I have defined three types of interfaces so far: Short - listing exported features only ("external" iface) Long - listing all the features ("internal" iface) Coded - Long, but with source code included (prettyfied source code) The modules are still under development, and they do not do yet everything I want them to do. There are some unfinished portions of the code; for example, the printer does not handle the classes properly yet, there are some formatting issues, export/import should be improved, etc. You should easily notice those shortcomings, because the samples I provide are not edited - this is what is _really_ produced by the tool. The good news is that all of those have been produced without XML or HTML formatting information - straight from the readable source code. But I use two lightweight helpers: single quoted words within comments become italic and the special banner --: separates groups of functions. I will stop explaining right now. You should be able to understand the tool solely from the above interfaces. If not, then it would mean that I have been wrong all along and that it is time for me to shut up. Jan