[Grace-core] Proposed rules for comments

[Reid Bradford Mitchell]

Here are the rules for comments that I am currently implementing. As discussed in the meeting yesterday, each node (inherited from baseNode) in the AST now starts with an empty list of commentNodes, where each commentNode has a field that stores the text of one comment line. We left open the question of where to attach commentNodes, so this is the solution that Prof. Bruce and I have decided I should work toward for now. Please let me know of any problems with this and/or changes I should make.

- For now, the AST will only store comments associated with var declarations, def declarations, method declarations, type declarations, and class definitions.

- Multi-line comments will be split into multiple commentNodes (one commentNode per line). Later, when certain commentNodes get associated with other nodes, all nodes with consecutive lines (representing a multi-line comment) will be associated with the same node.
examples:
// comment 1
// comment 2

// comment 3

…gives three different commentNodes

// comment 1
var x := 10 // comment 2

…gives two different commentNodes

- In general, entities will be associated with comments directly above or below their first line (method c {… or def x = 3), when there are no blank lines between the comments and the entities, and with partial-line comments placed at the end of their first line.
examples:

// A method that does something
method d { // A partial-line comment
// A method description inside the braces
// second line of description inside braces

def x = 100
return x
}

… results in the methodNode’s list of comments containing four commentNodes (directly above, same line, directly below, and the second line of the comment directly below).

// A method that does something
method d {

// A comment for def x
def x = 100 // A partial-line comment for def x
// A below-line comment for def x

return x
}

…results in the methodNode’s list of comments containing the first comment, and the defDecNode containing the other 3 commentNodes

- Partial-line comments will always be associated with the node created from the line they are on. All commentNodes have a field which says whether or not they are partial-line comments.

- If there is ambiguity about whether a non-partial-line comment should be associated with the entity above it or below it, associate it with the entity below.
example:

method d {

// A comment for def x
def x = 100 // A partial-line comment for def x
// An ambiguous comment that gets associated with def y
def y = 200

return x
}

… results in the defDecNode for x getting the first two comments, and the defDecNode for y getting the third comment. If this is not the intended result, you can put a blank line above the def y = 200 line to force all three comments to be associated with def x, and none with def y.

- Reid
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailhost.cecs.pdx.edu/pipermail/grace-core/attachments/20150609/13cdb6c9/attachment.html>