Software Engineering for Smart Data Analytics & Smart Data Analytics for Software Engineering

User Tools

Site Tools

commentT(#id, #parent, 'comment type')

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.


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. 

Parent Identification Heuristics

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.

Sample Java Source

 *  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


Its PEF Representation

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 Specification

        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]) 
research/jtransformer/api/java/pefs/4.2/commentt.txt · Last modified: 2018/05/09 01:59 (external edit)

SEWiki, © 2024