Positional cues or not

[Jan Skibinski]

On Tue, 13 Feb 2001, Armin Groesslinger wrote:

> I guess tools will get confused by
> 
> 
> data A = A Int
> 
> ---
> -- bla
> --
> 
> type B = String
> 
> ---
> -- blub
> 
> newtype C = C Bool
> 
> 
> Is "bla" and "blub" in 'before' or 'after' position?
> I don't like restrictions like disallowing empty lines before/after
> the comments to help the tool find the right comments.

	Right. The above examples indicate that not only
	the tools but also the human beings will be confused by the
	above sequence. You did not give a clue about the meaning
	of the "bla" and "blub" and hence I am not any wiser
	what they are referring to. Only when "blub" contextually
	refers to either entity "B" or entity "C" can a human
	reader make such association. But that proves the point
	that your example has the low level of readability: any
	additional time spent on sorting these things out in the
	reader's mind is a waste of his time.

	So this is not only a matter of "helping the tool find
	the right comments" but also a matter of readability
	of the sources. And that means that blank lines serve
	their purpose too and should be used with great care.
	No ambiguities arise when the comments are tightly
	coupled with entities they describe - whether they
	are before, after, or just at the beginning of the
	entities they belong to.

	By the way, I sometimes use "Jan's style" commenting
	even for datatype definitions, especially when I
	have something important to say there. This helps
	with very tight binding of the two. And when I move
	the things around the comments are not lost by some
	accident.

	newtype C
	    -- Some description .. 
	    =  C Bool
 
 	I suggest that both of your example comments "bla" and "blub"
	should be treated as floating comments: either as the
	decorations - which should be ignored alltogether, or
	as some sort of headers that have some global important
	meaning for the writer of the module. Look at the
	Hugs Prelude for example. There are plenty of such
	separators, grouping together the things that belong
	to numbers, to lists, etc. They are usually the "one liners"
	but on occasion you can also find a longer global
	description, as in module Random.
 
	Personally I use such separators to indicate categories
	of functions, which is helpful when number of functions
	in the module exceeds some readability level.
 	It helps to find the things and give extra meaning
	to the things inside the category.
	Those who viewed the samples I posted few days ago should
	have the clear idea how it works. Currently the extractor
	relies on an extra cue (at the moment it is --: Blah,
	but I was reminded that this is illegal according to the
	Report. Easy to change though).
		
	Categories are helpful things, unless one uses submodules
	instead. They exist in Smalltalk, Objective C, Eiffel.
	ISE Eiffel goes even one step further and insists on
	standard ctegory names all across their libraries.

	But the usage of headers in Hugs' Prelude goes beyond
	categories of functions; they also separate groups
	of methods, or combinations of datatypes and the
	functions, etc.

	Should the documention standard respect the module
	authors' wishes and provide at least some sort of support
	for 'categories'? I think, it should.

	Jan