
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. Using {--- -} is fine by me (with the restriction that they can only occur in the same places you can put a type signature). Cheers, Simon