SDA SE Wiki

Represents a comment.

#id: id
the unique ID assigned to this comment.

#parent: id
the ID of the fact that represents the element this comment is referring to. The parent element is determined based on a set of Parent Identification Heuristics.

#type: atom
One of these atoms:

• javaDoc: Indicates that this comment is a JavaDoc comment

         /**
          * This is a JavaDoc comment.
          */

• block: Indicates that this comment is a block comment

         /*
          * This is a block comment.
          */

• line: Indicates that this comment is a line comment

         // This is a line comment.
         // This is another one. Both refer to the next line of code.
         anobject.aMessage();

Because comments are abundant and often very long, two “optimisations” are performed:

1. Line comments are grouped whenever possible. Grouping means that multiple line comments are represented by a single

commentT/3 fact if they can be identified with a single contiguous text block that is not interrupted by statements

  or declarations. See the parent identification heuristics below. 
- commentT/3 facts do not include the comment text. Instead, for each commentT fact there is a [[slT|slT]] (sl = Source Location) fact with the same id. It represents the text range of the comment in the source code. slT/3 facts let you extract the comment text from the original source code, when needed. 

In order to decide to which declaration or statement a comment refers, JTransformer uses a set of heuristics derived from common best practice:

1. The parent of a JavaDoc comment is the next declaration after the comment.
2. The parent of a block comment is the next statement or declaration after the comment.
3. The parent of a line comment is
   1. the nearest AST element on the same line (if there is one), otherwise
   2. the closest AST element on a preceding or suceeding line in the same block. In this case
      • line comments with no intervening blank line or AST element are treated as a group,
      • closeness is measured in number of lines,
      • if a comment has the same distance to a preceding and a suceeding element, preference is given to the suceeding element.

For examples, see the comments in the sample Java source below.

/**
 *  This is a JavaDoc comment whose parent is the hello() method.
 */
public void hello(){
  
     /*
      *  This is a block comment whose parent is the variable declaration.
      */
     int variable;

     // These two line comments will be grouped together into a single 
     // commentT fact whose parent is the following declaration:
     int var2 = hello2(); // This one and the one below will also be grouped 
                          // and will also refer to the declaration of var2

}

In the following, commentT facts are nested below the AST elements to which they refer. This is just for readability and has no semantic implications:

methodT(#method, #class, 'hello', [], type(basic, void, 0), [], #block).
   commentT(#comment1, #method, 'javaDoc').                // The JavaDoc comment associated to the method declaration    
modifierT(#method, 'public').
blockT(#block, #method, #method, [#localdvar, V5]).
localT(#localvar, #block, #method, type(basic, int, 0), 'variable', 'null').
   commentT(#comment2, #localvar, 'blockComment').            // The block comment associated to the declaration of 'variable'
localT(#localvar2, #block, #method, type(basic, int, 0), 'var2', #call).
   commentT(#comment3, #localvar2, 'lineComment').           // The first two line comments grouped together in a single commentT fact
   commentT(#comment4, #localvar2, 'lineComment').           // The last two line comments grouped together in a single commentT fact
callT(#call, #parent, #method, 'null', 'hello2', [], V7).

ast_node_def('Java',commentT,[
	ast_arg(id,     mult(1,1,no ),	id,   [commentT]),
	ast_arg(parent, mult(1,1,no),	id,   [id]),
	ast_arg(kind,	mult(1,1,no ),	attr, [atom]) 
]).