A Haskell Documentation Standard

[Jan Skibinski]

On Tue, 30 Jan 2001, Simon Marlow wrote:

>    - a big win is that even without any annotations, you get
>      documentation for free (i.e. hyperlinked type signatures
>      for exported functions, class definitions, etc.).  Just having
>      this working would make we very happy :)

	Right, but without the comments.
	The question of compiler support aside ...

>      And there's an upgrade path: if we define the "interface-file"
>      format to be exactly the same as the syntax of a Haskell module
>      (perhaps with code optinoal), then the compiler can always just
>      read a source file and output the same file with types filled in.

	Am I missing something here? I thought that the Haskell Report
	does not the comments semantics. 
	They are the free floating entities, and can be put anywhere
	as it pleases a module developer. And we can have many possible
	types of comments describing: module, datatype, class, function,
	etc.
	Add to it some important decorations, delimiting some
	categories of functions, and we are in a complete mess.

	Granted the variety of styles used, how on earth even the
	cleverest parser can figure it out? Typical parsers (I am not
	talking here about HDoc) do not care because they skip the
	comments anyway but it is not the case for the documentation
	extractors.

	And the scheme: [(E1, C1), (E2, C2) ...] where (Ei,Ci)
	are pairs of top level entities and their associated
	comments, may work sometimes under the assumption that
	Ci always precedes Ei, but this is only the assumption
	which I can easily break anytime I wish: I can insert
	a category decoration somewhere in between or even reverse
	the order from Ci Ei to Ei Ci - what I often do because it
	pleases me so.

	This is the sad affair, because we could treat the problem
	the same way we treat the function signatures. The association
	between the function signatures (FSi) and their bodies (FBi)
	are not in any way positionally described. Sure, I have not
	seen a code whether someone writes:
	FS1 FS2 FS3 FB3 FB2 FB1, or FB1 FS1,
	but this is still OK - at least in Hugs, which I just checked
	to see if I am correct.

	There are few solutions possible:
	1. Describe precise positional standard for placement
	   of comments (see Eiffel (*) example)
	2. Invent markups to identify comment types and their
	   associations (see Java. But I am not talking here
	   about the variable markups, etc. for a moment.)
	3. Deliver development tools that force one particular
	   layout and use its own internal markup system, but
	   which is never visible to humans, unless they insist.
	   (See Smalltalk browsers enforcing the style. Eiffel
	   has it too, but admits old fashion editing, as long
	   as the result conforms to the standard.) 
	4. Bite a bullet and admit that comments are as important
	   as the code; extend Haskell Report to add those specialized
	   comments to be part of the language
	...... etc. 

	All of those have their problems however.

	Jan

	P.S.
	Because our first few messages are not stored in the
	haskelldoc archive I am again showing the pointer to Eiffel
	online book. Chapters 1 and 5 talk about documentation
	issues.

	http://www-staff.socs.uts.edu.au/~rist/eiffel/

	There are plenty of Eiffel sites. The oldest is the
	ISE site of Bertrand Meyer, the language inventor:

 	http://www.eiffel.com