Merge pull request INRIA#554 from tdurieux/feat_comments

.travis.yml

@@ -1,5 +1,7 @@
 language: java
 
+sudo: required
+
 jdk:
   - oraclejdk8
 

doc/_jekyll/_data/sidebar_doc.yml

@@ -95,6 +95,13 @@ entries:
           product: all
           version: all
 
+        - title: Comments
+          url: /comments.html
+          audience: writers, designers
+          platform: all
+          product: all
+          version: all
+
     - title: Querying source code elements
       audience: writers, designers
       platform: all

doc/comments.md

@@ -0,0 +1,69 @@
+---
+title: Comments
+keywords: comments
+last_updated: Mars 22, 2016
+---
+
+### Comments in Spoon
+
+In Spoon there are different kinds of comments:
+
+* Line comments (from // to end line)
+* Block comments (from /* to */)
+* Javadoc comments (from /** to */)
+
+#### Javadoc Comments
+
+The Javadoc comments are available via the API ```CtElement.getDocComment()``` and return a ```String```.
+
+#### Other Comments
+
+The block and line comments are represented with a ```CtComment``` class ([javadoc](http://spoon.gforge.inria.fr/mvnsites/spoon-core/apidocs/spoon/reflect/declaration/CtComment.html)). 
+This class exposes API to get the position and the content of the comment.
+
+We also try to understand to which element they are attached.
+We use simple heuristics that work well in nominal cases but it is not possible to address all specific cases.
+You can receive the comments of each ```CtElement``` via the API ```CtElement.getComments()``` that returns a ```List<CtComment>```.
+
+The reprint of the comments can be disable in the Environment.  
+
+##### Comment Attribution
+
+* Each comment can have multiple comments
+* Comments in the same line of a statement is attached to the statement
+* Comments which are alone in one line (or more than one lines) are associated to the first element following them. 
+* Comments cannot be associated to other comment
+* Comments at the end of a block are considered as orphans comment
+* Comments in a class level is attached to the class
+
+##### Comment Example
+Class comment
+```Java
+// class comment
+class A {
+  // class comment
+}
+```
+
+Statement comment
+```Java
+// Statement comment
+int a; // Statement comment
+```
+
+Orphan comment
+```Java
+try {
+
+} exception (Exception e) {
+  // Orphan comment
+}
+```
+
+Multiple line comment
+```Java
+// Statement comment 1
+// Statement comment 2 
+// Statement comment 3
+int a;
+```

src/main/java/spoon/reflect/code/CtComment.java

@@ -0,0 +1,58 @@
+/**
+ * Copyright (C) 2006-2015 INRIA and contributors
+ * Spoon - http://spoon.gforge.inria.fr/
+ *
+ * This software is governed by the CeCILL-C License under French law and
+ * abiding by the rules of distribution of free software. You can use, modify
+ * and/or redistribute the software under the terms of the CeCILL-C license as
+ * circulated by CEA, CNRS and INRIA at http://www.cecill.info.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the CeCILL-C License for more details.
+ *
+ * The fact that you are presently reading this means that you have had
+ * knowledge of the CeCILL-C license and that you accept its terms.
+ */
+package spoon.reflect.code;
+
+/**
+ * This code element defines a comment
+ *
+ */
+public interface CtComment extends CtStatement {
+	enum CommentType {
+		/**
+		 * before the package line (typically the license)
+		 */
+		FILE,
+		/**
+		 * JavaDoc comment: before methods, fields, types
+		 */
+		JAVADOC,
+		/**
+		 * Inline comment (//)
+		 */
+		INLINE,
+		/**
+		 * Block comment (/* *\/)
+		 */
+		BLOCK
+	}
+
+	/**
+	 * Get the content of the comment
+	 * @return the content of the comment
+	 */
+	String getContent();
+
+	<E extends CtComment> E setContent(String content);
+
+	/**
+	 * Get the type of the comment
+ 	 * @return the comment type
+	 */
+	CommentType getCommentType();
+
+	<E extends CtComment> E setCommentType(CommentType commentType);
+}

src/main/java/spoon/reflect/declaration/CtElement.java

@@ -17,6 +17,7 @@
 package spoon.reflect.declaration;
 
 import spoon.processing.FactoryAccessor;
+import spoon.reflect.code.CtComment;
 import spoon.reflect.cu.SourcePosition;
 import spoon.reflect.reference.CtReference;
 import spoon.reflect.reference.CtTypeReference;
@@ -74,7 +75,7 @@ <A extends Annotation> CtAnnotation<A> getAnnotation(
 
 	/**
 	 * Returns the text of the documentation ("javadoc") comment of this
-	 * element.
+	 * element. The documentation is also accessible via {@link #getComments()}.
 	 */
 	String getDocComment();
 
@@ -119,7 +120,9 @@ <A extends Annotation> CtAnnotation<A> getAnnotation(
 
 	/**
 	 * Sets the text of the documentation ("javadoc") comment of this
-	 * declaration.
+	 * declaration. This API will set the content of the first javadoc
+	 * {@link CtComment} or create a new  javadoc {@link CtComment} if
+	 * no javadoc {@link CtComment} is available on this object.
 	 */
 	<E extends CtElement> E setDocComment(String docComment);
 
@@ -253,4 +256,28 @@ <E extends CtElement> List<E> getAnnotatedChildren(
 	 * Returns the metadata keys stored in an element.
 	 */
 	Set<String> getMetadataKeys();
+
+	/**
+	 * Set the comment list
+	 */
+	<E extends CtElement> E setComments(List<CtComment> comments);
+
+	/**
+	 * The list of comments
+	 * @return the list of comment
+	 */
+	List<CtComment> getComments();
+
+	/**
+	 * Add a comment to the current element
+	 * <code>element.addComment(element.getFactory().Code().createComment("comment", CtComment.CommentType.INLINE)</code>
+	 * @param comment the comment
+	 */
+	<E extends CtElement> E addComment(CtComment comment);
+
+	/**
+	 * Remove a comment
+	 * @param comment the comment to remove
+	 */
+	<E extends CtElement> E removeComment(CtComment comment);
 }

src/main/java/spoon/reflect/factory/CodeFactory.java

@@ -24,6 +24,7 @@
 import spoon.reflect.code.CtCatchVariable;
 import spoon.reflect.code.CtCodeSnippetExpression;
 import spoon.reflect.code.CtCodeSnippetStatement;
+import spoon.reflect.code.CtComment;
 import spoon.reflect.code.CtConstructorCall;
 import spoon.reflect.code.CtExpression;
 import spoon.reflect.code.CtFieldAccess;
@@ -531,4 +532,25 @@ public CtCodeSnippetStatement createCodeSnippetStatement(String statement) {
 		e.setValue(statement);
 		return e;
 	}
+
+	/**
+	 * Creates a comment
+	 *
+	 * @param content The content of the comment
+	 * @param type The comment type
+	 * @return a new CtComment
+	 */
+	public CtComment createComment(String content, CtComment.CommentType type) {
+		return factory.Core().createComment().setContent(content).setCommentType(type);
+	}
+
+	/**
+	 * Creates an inline comment
+	 *
+	 * @param content The content of the comment
+	 * @return a new CtComment
+	 */
+	public CtComment createInlineComment(String content) {
+		return createComment(content, CtComment.CommentType.INLINE);
+	}
 }

src/main/java/spoon/reflect/factory/CoreFactory.java

@@ -29,6 +29,7 @@
 import spoon.reflect.code.CtCatchVariable;
 import spoon.reflect.code.CtCodeSnippetExpression;
 import spoon.reflect.code.CtCodeSnippetStatement;
+import spoon.reflect.code.CtComment;
 import spoon.reflect.code.CtConditional;
 import spoon.reflect.code.CtConstructorCall;
 import spoon.reflect.code.CtContinue;
@@ -443,6 +444,11 @@ SourcePosition createSourcePosition(
 	 */
 	CtCodeSnippetStatement createCodeSnippetStatement();
 
+	/**
+	 * Creates a comment.
+	 */
+	CtComment createComment();
+
 	/**
 	 * Gets the main factory of that core factory (cannot be <code>null</code>).
 	 */

src/main/java/spoon/reflect/visitor/CtAbstractVisitor.java

@@ -16,8 +16,6 @@
  */
 package spoon.reflect.visitor;
 
-import java.lang.annotation.Annotation;
-
 import spoon.reflect.code.CtAnnotationFieldAccess;
 import spoon.reflect.code.CtArrayRead;
 import spoon.reflect.code.CtArrayWrite;
@@ -31,6 +29,7 @@
 import spoon.reflect.code.CtCatchVariable;
 import spoon.reflect.code.CtCodeSnippetExpression;
 import spoon.reflect.code.CtCodeSnippetStatement;
+import spoon.reflect.code.CtComment;
 import spoon.reflect.code.CtConditional;
 import spoon.reflect.code.CtConstructorCall;
 import spoon.reflect.code.CtContinue;
@@ -90,6 +89,8 @@
 import spoon.reflect.reference.CtTypeReference;
 import spoon.reflect.reference.CtUnboundVariableReference;
 
+import java.lang.annotation.Annotation;
+
 /** Provides an empty implementation of CtVIsitor.
  *  See {@link CtScanner} for a much more powerful implementation of CtVisitor.
  */
@@ -447,4 +448,9 @@ public <T> void visitCtFieldWrite(CtFieldWrite<T> fieldWrite) {
 	public <T> void visitCtSuperAccess(CtSuperAccess<T> f) {
 
 	}
+
+	@Override
+	public void visitCtComment(CtComment comment) {
+
+	}
 }

src/main/java/spoon/reflect/visitor/CtInheritanceScanner.java

@@ -33,6 +33,7 @@
 import spoon.reflect.code.CtCodeElement;
 import spoon.reflect.code.CtCodeSnippetExpression;
 import spoon.reflect.code.CtCodeSnippetStatement;
+import spoon.reflect.code.CtComment;
 import spoon.reflect.code.CtConditional;
 import spoon.reflect.code.CtConstructorCall;
 import spoon.reflect.code.CtContinue;
@@ -834,6 +835,14 @@ public <T> void visitCtVariableWrite(CtVariableWrite<T> e) {
 		scanCtVisitable(e);
 	}
 
+	@Override
+	public void visitCtComment(CtComment e) {
+		scanCtElement(e);
+		scanCtVisitable(e);
+		scanCtStatement(e);
+		scanCtCodeElement(e);
+	}
+
 	public <T> void visitCtAnnotationFieldAccess(
 			CtAnnotationFieldAccess<T> e) {
 		visitCtVariableRead(e);