[Grace-core] Comment proposal

[Michael Homer]

My comment query got some response, including Andrew off-list
indicating that his intention in writing that passage was that it
would restrict the allowable placement of comments. I am proposing a
simplification of the rule:

1) A comment must occupy a complete physical line at statement level,
up to indentation.
2) The comment is semantically attached to the statement or
declaration on the following line.
3) Comments followed by blank lines or a closing brace are freestanding.
4) (Optionally) A comment may also appear on a complete line
immediately before a part of a multi-part method name, and is attached
to that part.
5) (Optionally) A comment may also appear on a complete line
immediately before a parameter declaration, and is attached to that
parameter.
6) A comment not conforming to the above is a syntax error.

The advantage of this approach is that there is one and only one
location for the comment attached to any given node, and one and only
one node that a given comment could be attached to, and it's very
clear what they are. It makes the right thing to do stylistically be
the only thing that works, like with indentation.

Overlaid rules about backwards and forwards attachment and syntactic
units are non-obvious to the (particularly, novice) user and will lead
to confusion about what is attached where and where they may be
placed. Rare corner cases where comments can't be placed are
unhelpful, but universal placement isn't compatible with affixing
comments to their referents and drastically complicates the syntax.

This rule is always unambiguous, allows straightforward corrective
error messages, and allows attaching comments to everything that
should need documentation while prohibiting the perverse placements
identified earlier.
-Michael