<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class="">
<div class="">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.</div>
<div class=""><br class="">
</div>
<div class="">- For now, the AST will only store comments associated with var declarations, def declarations, method declarations, type declarations, and class definitions.</div>
<div class=""><br class="">
</div>
<div class="">- 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.</div>
<div class="">examples:</div>
<div class=""><font face="Courier New" class="">// comment 1</font></div>
<div class=""><font face="Courier New" class="">// comment 2</font></div>
<div class=""><font face="Courier New" class=""><br class="">
</font></div>
<div class=""><font face="Courier New" class="">// comment 3</font></div>
<div class=""><br class="">
</div>
<div class="">…gives three different commentNodes</div>
<div class=""><br class="">
</div>
<div class=""><font face="Courier New" class="">// comment 1</font></div>
<div class=""><font face="Courier New" class="">var x := 10 // comment 2</font></div>
<div class=""><br class="">
</div>
<div class="">…gives two different commentNodes</div>
<div class=""><br class="">
</div>
<div class="">- In general, entities will be associated with comments directly above or below their first line (<font face="Courier New" class="">method c {…</font> or <font face="Courier New" class="">def x = 3</font>), 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.</div>
<div class="">examples:</div>
<div class=""><br class="">
</div>
<div class=""><font face="Courier New" class="">// A method that does something</font></div>
<div class=""><font face="Courier New" class="">method d { // A partial-line comment</font></div>
<div class=""><font face="Courier New" class=""><span class="Apple-tab-span" style="white-space: pre;"></span>// A method description inside the braces</font></div>
<div class=""><font face="Courier New" class=""><span class="Apple-tab-span" style="white-space: pre;"></span>// second line of description inside braces</font></div>
<div class=""><font face="Courier New" class=""><br class="">
</font></div>
<div class=""><font face="Courier New" class=""><span class="Apple-tab-span" style="white-space: pre;"></span>def x = 100</font></div>
<div class=""><font face="Courier New" class=""><span class="Apple-tab-span" style="white-space: pre;"></span>return x</font></div>
<div class=""><font face="Courier New" class="">}</font></div>
<div class=""><font face="Courier New" class=""><br class="">
</font></div>
<div class="">… 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).</div>
<div class=""><font face="Arial" class=""><br class="">
</font></div>
<div class="">
<div class=""><font face="Courier New" class="">// A method that does something</font></div>
<div class=""><font face="Courier New" class="">method d {</font></div>
<div class=""><font face="Courier New" class=""><br class="">
</font></div>
<div class=""><font face="Courier New" class=""><span class="Apple-tab-span" style="white-space: pre;"></span>// A comment for def x</font></div>
<div class=""><font face="Courier New" class=""><span class="Apple-tab-span" style="white-space: pre;"></span>def x = 100 // A partial-line comment for def x</font></div>
<div class=""><font face="Courier New" class=""><span class="Apple-tab-span" style="white-space: pre;"></span>// A below-line comment for def x</font></div>
<div class=""><font face="Courier New" class=""><br class="">
</font></div>
<div class=""><font face="Courier New" class=""><span class="Apple-tab-span" style="white-space: pre;"></span>return x</font></div>
<div class=""><font face="Courier New" class="">}</font></div>
</div>
<div class=""><font face="Courier New" class=""><br class="">
</font></div>
<div class="">…results in the methodNode’s list of comments containing the first comment, and the defDecNode containing the other 3 commentNodes</div>
<div class=""><br class="">
</div>
<div class="">- 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.</div>
<div class=""><br class="">
</div>
<div class="">- 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.</div>
<div class="">example:</div>
<div class=""><br class="">
</div>
<div class="">
<div class=""><span class="" style="font-family: 'Courier New';">method d {</span></div>
<div class=""><font face="Courier New" class=""><br class="">
</font></div>
<div class=""><font face="Courier New" class=""><span class="Apple-tab-span" style="white-space: pre;"></span>// A comment for def x</font></div>
<div class=""><font face="Courier New" class=""><span class="Apple-tab-span" style="white-space: pre;"></span>def x = 100 // A partial-line comment for def x</font></div>
<div class=""><font face="Courier New" class=""><span class="Apple-tab-span" style="white-space: pre;"></span>// An ambiguous comment that gets associated with def y</font></div>
<div class=""><font face="Courier New" class=""><span class="Apple-tab-span" style="white-space: pre;"></span>def y = 200</font></div>
<div class=""><font face="Courier New" class=""><br class="">
</font></div>
<div class=""><font face="Courier New" class=""><span class="Apple-tab-span" style="white-space: pre;"></span>return x</font></div>
<div class=""><font face="Courier New" class="">}</font></div>
</div>
<div class=""><br class="">
</div>
<div class="">… results in the defDecNode for <font face="Courier New" class="">x</font> getting the first two comments, and the defDecNode for <font face="Courier New" class="">y </font>getting the third comment. If this is not the intended result, you can
put a blank line above the <font face="Courier New" class="">def y = 200 </font>line to force all three comments to be associated with <font face="Courier New" class="">def x</font>, and none with <font face="Courier New" class="">def y</font>.</div>
<div class=""><br class="">
</div>
<div class="">- Reid</div>
</body>
</html>