restarting the discussion

[Jan Skibinski]

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