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