Simon Marlow 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