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