SDA SE Wiki

Represents a comment. The commentT fact just gives information about the existence and the type of the comment, not about the content (the comment itself). The content of a comment is represented by the commentTextT fact, which can be enabled in the JTransformer Preferences.

#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.
          */

• blockComment: Indicates that this comment is a block comment

         /*
          * This is a block comment.
          */

• lineComment: 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, _, 'hello', [], _, [] ,[], Block),
  commentT(JavaDocComment, Method, 'javaDoc'),         // The JavaDoc comment associated to the method declaration  
localT(Variable, Block, Method, _, 'variable', null),
  commentT(BlockComment, Variable, 'block'),
localT(Var2, Block, Method, _, 'var2', _),             // The block comment associated to the declaration of 'variable'
   commentT(LineComment1, Var2, 'lineComment'),        // The first two line comments grouped together in a single commentT fact
   commentT(LineComment2, Var2, 'lineComment').        // The last two line comments grouped together in a single commentT fact

ast_node_type_spec(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, [atomic]) 
]).