SDA SE Wiki

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

User Tools

Site Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

research:jtransformer:api:java:pefs:2.9:commentt [2018/05/09 01:59] (current)
Line 1: Line 1:
 +{{page>​prologast_bodypef_index&​fullpage&​nofooter}}
 +
 +=== commentT(#​id,​ #parent, '​type'​) ​ ===
 +
 +Represents a comment.  ​
 +
 +
 +=== Arguments ===
 +
 +==  ==
 +**#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
 +<Code lang-java>​
 +         /**
 +          * This is a JavaDoc comment.
 +          */
 +</​Code>​
 +    * ''​block'': ​  ​Indicates that this comment ​ is a block comment ​
 +<Code lang-java>​
 +         /*
 +          * This is a block comment.
 +          */
 +</​Code>​
 +    * ''​line'': ​   Indicates that this comment is a line comment ​
 +<Code lang-java>​
 +
 +         // This is a line comment.
 +         // This is another one. Both refer to the next line of code.
 +         ​anobject.aMessage();​
 +</​Code>​
 +   
 +=== Optimisations ===
 + ​Because comments are abundant and often very long, two "​optimisations"​ are performed:
 +  - 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: ​
 +  - The parent of a JavaDoc comment is the next declaration after the comment.
 +  - The parent of a block comment is the next statement or declaration after the comment.
 +  - The parent of a line comment is
 +    - the nearest AST element on the same line (if there is one), otherwise
 +    - 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 ===
 +
 +==  ==
 +<Code lang-java>​
 +/**
 + ​* ​ 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
 +
 +}
 +</​Code>​
 +
 +
 +=== 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:​
 +==  ==
 +<Code lang-prolog>​
 +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).
 +</​Code>​
 +
 +=== AST Specification ===
 +== ==
 +<​Code>​
 +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]) ​
 +]).
 +</​Code>​
  
research/jtransformer/api/java/pefs/2.9/commentt.txt · Last modified: 2018/05/09 01:59 (external edit)

SEWiki, © 2019