Positional cues or not

[Simon Marlow]

> > 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.  

The point I was make (badly) is that in order to incorporate
documentation support into a Haskell parser, the natural thing to do
would be to teach the lexer about documentation comments, and pass them
through to the parser as tokens.  Positional cues make this harder,
because the lexer has to know  a lot more about the context in order to
do its job.  Annotating documentation comments using a different style,
like {--- -} or ---, make the job easier again.

To be clear, I'm not arguing *against* positional cues, I'm arguing
*for* using a distinctive comment style for documentation comments.

Of course, you don't have to do this using a Haskell parser.  My feeling
is that this is a good idea however, since the tool needs to understand
some Haskell in order to properly hyperlink and pretty print the type
signatures & source.

> 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.

fine. :)

Cheers,
	Simon