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 {--- -}. Regards, Malcolm