Positional cues or not

[Henrik Nilsson]

Marcin Kowalczyk wrote:
> > It would also be nice if both end-of-line comments and brace comments
> > could be used for documentation purposes, since people clearly have
> > different preferences. This suggets a convention which is similar for
> > the two cases.
> 
> I don't think we should complicate the design and implementation for
> such case. Brace comments are used to insert a small comment in the
> middle of a line or comment out a large piece of code. I would stick
> to end-of-line comments for documentation purposes.

I don't think it is that complicated. When the lexer encounters a
comment (end-of-line or brace), it checks whether the next token
is a special tag. If so, we're in documentation mode, if not, we're
not. Lexing in the two cases (as long as we're not supporting
nested brace comments inside documentation, and I cannot see why
one would like to do that) would be largely the same, with minor
differences for handling line breaks/detecting the end of the
documentation comment.

So, regardless of whether we use positional cues or special marking
for identifying the documentation comments, is there any really good
reason for not allowing documentation comments in either of the
two available Haskell commenting styles? If not, then maybe we
can decide on allowing both and have one thing less to argue about!

I guess people like Malcolm Wallace and Simon Marlow are in a good
position to answer the above question. (For what it is worth: As long
as there is some easy way for the lexer to recognize a documentation
comment, I cannot see that supporting both styles would complicate
the lexer in my (as far as scanning and parsing are concerned)
Haskell compiler in any significant way.) 

In Jan Skibinski's module extractor, I believe the documentation
comments are identified by the parser rather than the scanner.
Jan, is that correct? If so, how much more difficult would it be
to support both commenting styles in that case?

Still, I think it would be good if the conventions are such that a
lexer can recognize the documentation comments. Implementation
issues apart, that would be consistent with the current design for
pragmas which have a lot in common with documentation comments.


Regards,

/Henrik

-- 
Henrik Nilsson
Yale University
Department of Computer Science
nilsson@cs.yale.edu