feat(comment): WIP Adds comments in the AST

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/compiler/Environment.java

@@ -296,6 +296,16 @@ void report(Processor<?> processor, Level level,
 	 */
 	void setGenerateJavadoc(boolean generateJavadoc);
 
+	/**
+	 * Returns the value of the option generate-comments.
+	 */
+	boolean isGenerateComments();
+
+	/**
+	 * Sets the option generate-comments to generate comments of the project on the source generated.
+	 */
+	void setGenerateComments(boolean generateComments);
+
 	/**
 	 * Gets the factory of the environment.
 	 */

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

@@ -0,0 +1,33 @@
+/**
+ * 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;
+
+import spoon.reflect.declaration.CtElement;
+
+/**
+ * This code element defines a comment
+ *
+ */
+public interface CtComment extends CtElement, CtStatement {
+	String getContent();
+
+	boolean isInline();
+
+	<E extends CtComment> E setContent(String content);
+
+	<E extends CtComment> E setInline(boolean inline);
+}

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;
@@ -253,4 +254,16 @@ <E extends CtElement> List<E> getAnnotatedChildren(
 	 * Returns the metadata keys stored in an element.
 	 */
 	Set<String> getMetadataKeys();
+
+	<E extends CtElement> E setComments(List<CtComment> comments);
+
+	/**
+	 * The list of comments
+	 * @return the list of comment
+	 */
+	List<CtComment> getComments();
+
+	<E extends CtElement> E addComment(CtComment comment);
+
+	<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,15 @@ public CtCodeSnippetStatement createCodeSnippetStatement(String statement) {
 		e.setValue(statement);
 		return e;
 	}
+
+	/**
+	 * Creates a comment
+	 *
+	 * @param content The content of the comment
+	 * @param isInline True if the comment is inline otherwise it is a block comment
+	 * @return a new CtComment
+	 */
+	public CtComment createComment(String content, boolean isInline) {
+		return factory.Core().createComment().setContent(content).setInline(isInline);
+	}
 }

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);