On Mon, 12 Feb 2001, John Meacham wrote:

Another reason to use a distinctive document style is that comments are often used to do things like block out unwanted code, or comment out blocks which are not needed in hugs say but are in ghc (under the presumption someone will go in and edit it later).

These are always {- -}. I would use end-of-line comments for all kinds of documentation. We have more choices than the number of introducing dashes: -- This is Manuel's style of comments. -- Note the empty comment below: -- foo :: Some -> Interesting -> Type For example we could simply decide that a documentation comment must come just before the type signature, without intervening all-whitespace line. Comments for larger blocks of definitions have at least one empty line after them and would be skipped. -- Marcin 'Qrczak' Kowalczyk

On Mon, 12 Feb 2001 malcolm-hs@cs.york.ac.uk wrote:

Well, I frequently use end-of-line comments for blocking out dead code. And this often ends up in exactly the place where a documentation comment might occur, for instance:

myFunctionF x y z = -- map (g . unlines . f . lines . something) (z x) -- is this wrong? map (f . unlines . g . lines . something) (z x)

No, this is not wrong but one could argue that the dead code shouldn't be present in the final version of source code. And, as a side effect, an interface tool could help you with finding such things. Jan

malcolm-hs@cs.york.ac.uk wrote:

So, on balance, it looks like we really need special doc comments so tools don't get confused.

Having looked at the various pros and cons which have been discuessed so far, I'm in favour of specially marked documentation comments since they give explicit control over what is intended for documentation, and since they give additional flexibility for distinguishing different KINDS of documentation comments (e.g. internal vs. external, beginner's index vs. programmer's index, etc.), should that be desired (now or in the future). 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 -- -- -- ... -- 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). Both of these are certainly sufficiently simple for a lexer to deal with. Another advantage is that there could be a few different tags for identifying different classes of documentation comments. Best regards, /Henrik -- Henrik Nilsson Yale University Department of Computer Science nilsson@cs.yale.edu

Marcin Kowalczyk wrote:

...

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.

I don't think we should complicate the design and implementation for such case. Brace comments are used to insert a small comment in the middle of a line or comment out a large piece of code. I would stick to end-of-line comments for documentation purposes.

I don't think it is that complicated. When the lexer encounters a comment (end-of-line or brace), it checks whether the next token is a special tag. If so, we're in documentation mode, if not, we're not. Lexing in the two cases (as long as we're not supporting nested brace comments inside documentation, and I cannot see why one would like to do that) would be largely the same, with minor differences for handling line breaks/detecting the end of the documentation comment. So, regardless of whether we use positional cues or special marking for identifying the documentation comments, is there any really good reason for not allowing documentation comments in either of the two available Haskell commenting styles? If not, then maybe we can decide on allowing both and have one thing less to argue about! I guess people like Malcolm Wallace and Simon Marlow are in a good position to answer the above question. (For what it is worth: As long as there is some easy way for the lexer to recognize a documentation comment, I cannot see that supporting both styles would complicate the lexer in my (as far as scanning and parsing are concerned) Haskell compiler in any significant way.) In Jan Skibinski's module extractor, I believe the documentation comments are identified by the parser rather than the scanner. Jan, is that correct? If so, how much more difficult would it be to support both commenting styles in that case? Still, I think it would be good if the conventions are such that a lexer can recognize the documentation comments. Implementation issues apart, that would be consistent with the current design for pragmas which have a lot in common with documentation comments. Regards, /Henrik -- Henrik Nilsson Yale University Department of Computer Science nilsson@cs.yale.edu

Henrik Nilsson wrote,

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...