Positional cues or not

[Henrik Nilsson]

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