Henrik Nilsson
I'm not too worried about noise in this case: noise is always something relative, and I'd expect that the syntactic overhead of the marking will not be significant in comparison to the average size of documentation comments.
Regarding the marking conventions, I agree with Simon Marlow that it would be nice if the conventions are sufficiently simple so that the lexer easily can identify them.
It would also be nice if both end-of-line comments and brace comments could be used for documentation purposes, since people clearly have different preferences. This suggets a convention which is similar for the two cases.
One proposal was to allow both something like
{--- -}
and
-- -- -- ... --
I am with you up to this point, as it makes lexing much simpler. This way, the lexer knows that it is handling documentation without the need for contextual information. I agree with Marcin that it would be sufficient to use end-of-line comments for documentation, but on the other hand, I also accept your point about having one thing less to argue if we just allow both styles (seems to be a small enough price for a simplification of the decision process).
This is OK, but maybe a little too subtle. E.g. one might be forgiven for wondering why not writing ---- or {- --.
On the other hand, generalizing Simon's tagged proposal seems to work well:
{- @DOC ... -}
and
-- @DOC -- .. --
where I took the liberty to add a @ in front of DOC (which might be a suitable convention for all special tags).
However, I don't agree with this anymore. The argument above - for having tags at all - was one of simplifying the lexer. Now, suddenly, you come with an argument about subtlety, which certainly cannot be anything the lexer cares about. And as far as humans go, I would prefer to drop the tags altogether rather than making them more visible. Remember, the main tool in which code is looked at is an ASCII text editor. We have to optimise the notation for that and in a text editor I don't care what is documentation and what not, because *all* comments are documentation. Moreover, Haskell's syntactic design follows the principle of minimality - I don't think, it would be wise to diverge from that for the documentation standard. Just to reenforce the point about how annoying tags are in a a text editor. How am I supposed to format (in ASCII) my documentation? Like this -- -- -- A cool function that does wonderful things and all of -- them automatically -- foo :: Some -> cool -> type Looks ugly. So how about -- -- A cool function that does wonderful things and all of -- them automatically -- foo :: Some -> cool -> type Doesn't look too bad, but is very annoying to use in Emacs filladapt mode. I don't know about you, but when I write comments[1], I don' want to do all the line breaks and paragraph formatting manually. Emacs is clever enough that it can do automatic paragraph formatting within code comments. However, the second of the above styles kills its standard algorithm. When I press M-q (= fill-paragraph-or-region) on the above comment, I get -- -- A cool function that does wonderful things and all -- -- of -- them automatically -- foo :: Some -> cool -> type which is certainly not what I want. Summary: Any kinds of tags that interfere with the use and formatting of comments in a standard text editor are BAD. Anby kind of tags that are visually imposing are ugly. Cheers, Manuel PS: Looking at public Haskell code in general, it seems not many Haskell programmers except me comment their programs anyway...