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