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

Both sides previous revision Previous revision
Next revision
Previous revision
research:jtransformer:api:java:pefs:4.0:commentt [2014/08/13 13:31]
127.0.0.1 external edit
research:jtransformer:api:java:pefs:4.0:commentt [2018/05/09 01:59] (current)
Line 1: Line 1:
 +{{page>​prologast_bodypef_index&​fullpage&​nofooter}}
 +
 +=== 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|commentTextT]] fact, which can be enabled in the JTransformer Preferences.
 +
 +
 +=== 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>​
 +    * ''​blockComment'': ​  ​Indicates that this comment ​ is a block comment ​
 +<Code lang-java>​
 +         /*
 +          * This is a block comment.
 +          */
 +</​Code>​
 +    * ''​lineComment'': ​   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,​ _, '​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
 +</​Code>​
 +
 +=== AST Specification ===
 +== ==
 +<​Code>​
 +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]) ​
 +]).
 +</​Code>​
  
research/jtransformer/api/java/pefs/4.0/commentt.txt · Last modified: 2018/05/09 01:59 (external edit)

SEWiki, © 2019