Positional cues or not

Manuel M. T. Chakravarty chak@cse.unsw.edu.au
Sat, 10 Feb 2001 12:20:57 +1100


Simon Marlow <simonmar@microsoft.com> wrote,

> > > I don't particularly care whether the convention is {--- -} 
> > or {-# DOC #-}
> > > (with a slight preference for the latter, because it is consistent
> > > with existing conventions).
> > 
> > I have a distinct preference against {-# DOC #-}.  It is too visually
> > dense and distracting.  Besides, the simpler {- -} is a perfectly
> > good convention already as well.
> > 
> > I'm not sure whether to require the extra markup of {--- -}.  For one
> > thing, as Manuel pointed out, people often use -- to end of line
> > comments in addition to nested comments, and I think we should be
> > able to be flexible there.  However, if you think special markup to
> > distinguish documentation comments from normal comments is really
> > necessary, maybe a three-dash --- to end of line could serve as the
> > analog to {--- -}.
> 
> Using simple {- -} is too hard to parse; the lexer can't pass these on
> to the parser as tokens, because they can occur anywhere.

I am not sure what you mean to imply here.  This is only
something the Doc tool has to do, isn't it.  The mere fact
that a comment immediately preceeds an (exported) type
signature could be enough of a cue to turn it into a
documentation comment.  

More problematic are general comments not associated with a
single definition that the programmer might want to have in
the generated documentation.

I also tend to think that {-# DOC #-} is too heavy.
However, a convention that I am already using for years is
to format my comments belonging to an exported entity such
that it starts with a brief one line description of what the
function or type is about.  If the entity is exported, I
close that sentence with "(EXPORTED)".  This admittedly is
also visually heavy, but it is also helpful information when
browsing the file in an editor, so I think, the heaviness is
less problematic.

Cheers,
Manuel