feat(comment): Avoid parsing javadoc when it isn't necessary.

doc/command_line.md

@@ -2,7 +2,7 @@
 title: Command Line
 tags: [usage]
 keywords: command, line, usage, java, jar
-last_updated: October 1, 2015
+last_updated: May 25, 2016
 ---
 
 To run Spoon in command line, you first have to download the corresponding jar file.
@@ -35,10 +35,6 @@ Options :
 
   [-h|--help]
 
-  [-v|--verbose]
-        Argument deprecated, see the argument level. Output messages about what
-        the compiler is doing.
-
   [--tabs]
         Use tabulations instead of spaces in the generated code (use spaces by
         default).
@@ -50,10 +46,6 @@ Options :
         Level of the ouput messages about what spoon is doing. Default value is
         ALL level. (default: OFF)
 
-  [--vvv]
-        Argument deprecated, see the argument level. Generate all debugging
-        info.
-
   [--with-imports]
         Enable imports in generated files.
 
@@ -64,9 +56,6 @@ Options :
         Forces the compiler to use a specific encoding (UTF-8, UTF-16, ...).
         (default: UTF-8)
 
-  [(-s|--spoonlet) <spoonlet>]
-        List of spoonlet files to load.
-
   [(-i|--input) <input>]
         List of path to sources files.
 
@@ -130,5 +119,14 @@ Options :
         Disable the copy of resources from source to destination folder.
 
   [-j|--generate-javadoc]
-        Enable the generation of the javadoc.
+        Enable the generation of the javadoc. Deprecated, use enable-comments
+        argument.
+
+  [-c|--enable-comments]
+        Adds all code comments in the Spoon AST (Javadoc, line-based comments),
+        rewrites them when pretty-printing.
+
+  [(-f|--generate-files) <generate-files>]
+        Only generate the given fully qualified java classes (separated by ':'
+        if multiple are given).
 ```

doc/comments.md

@@ -1,28 +1,28 @@
 ---
 title: Comments
 keywords: comments
-last_updated: April 18, 2016
+last_updated: May 25, 2016
 ---
 
 In Spoon there are four different kinds of comments:
 
-* File comments (comment at the begin of the file, generally licence) ```CtComment.CommentType.FILE```
-* Line comments (from // to end line) ```CtComment.CommentType.INLINE```
-* Block comments (from /* to */) ```CtComment.CommentType.BLOCK```
-* Javadoc comments (from /** to */) ```CtComment.CommentType.JAVADOC```
+* File comments (comment at the begin of the file, generally licence) `CtComment.CommentType.FILE`
+* Line comments (from // to end line) `CtComment.CommentType.INLINE`
+* Block comments (from /* to */) `CtComment.CommentType.BLOCK`
+* Javadoc comments (from /** to */) `CtComment.CommentType.JAVADOC`
 
-The comments are represented in Spoon 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 content of the comment ```CtComment.getContent()```, the type of the comment ```CtComment.getCommentType()``` and the position ```CtComment.getPosition()```.
+The comments are represented in Spoon 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 content of the comment `CtComment.getContent()`, the type of the comment `CtComment.getCommentType()` and the position `CtComment.getPosition()`.
 
 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()``` which returns a ```List<CtComment>```.
+You can receive the comments of each `CtElement` via the API `CtElement.getComments()` which returns a `List<CtComment>`.
 
-The reprint of the comments can be disable in the Environment via the option ```Environment.setGenerateJavadoc(boolean)```.  
+The parsing of the comments can be disable in the Environment via the option `Environment.setCommentsEnable(boolean)` or the argument `--enable-comments` (or `-c`) with the command line.  
 
 ## Javadoc Comments
 
-The Javadoc comments are also available via the API ```CtElement.getDocComment()``` but this API returns directly the content of the Javadoc as ```String```.
+The Javadoc comments are also available via the API `CtElement.getDocComment()` but this API returns directly the content of the Javadoc as `String`.
 
 ## Comment Attribution
 
@@ -34,7 +34,9 @@ The Javadoc comments are also available via the API ```CtElement.getDocComment()
 * Comments in a class level is attached to the class
 
 ### Comment Examples
+
 Class comment
+
 ```java
 // class comment
 class A {
@@ -43,12 +45,14 @@ class A {
 ```
 
 Statement comment
+
 ```java
 // Statement comment
 int a; // Statement comment
 ```
 
 Orphan comment
+
 ```java
 try {
 
@@ -58,6 +62,7 @@ try {
 ```
 
 Multiple line comment
+
 ```java
 // Statement comment 1
 // Statement comment 2 
@@ -67,7 +72,7 @@ int a;
 
 ## Process Comments
 
-You can process comments like every ```CtElement```.
+You can process comments like every `CtElement`.
 
 ```java
 public class CtCommentProcessor extends AbstractProcessor<CtComment> {

src/main/java/spoon/Launcher.java

@@ -375,7 +375,15 @@ protected static JSAP defineArgs() {
 			sw1 = new Switch("generate-javadoc");
 			sw1.setShortFlag('j');
 			sw1.setLongFlag("generate-javadoc");
-			sw1.setHelp("Enable the generation of the javadoc.");
+			sw1.setHelp("Enable the generation of the javadoc. Deprecated, use enable-comments argument.");
+			sw1.setDefault("false");
+			jsap.registerParameter(sw1);
+
+			// Enable generation of javadoc.
+			sw1 = new Switch("enable-comments");
+			sw1.setShortFlag('c');
+			sw1.setLongFlag("enable-comments");
+			sw1.setHelp("Adds all code comments in the Spoon AST (Javadoc, line-based comments), rewrites them when pretty-printing.");
 			sw1.setDefault("false");
 			jsap.registerParameter(sw1);
 
@@ -419,6 +427,7 @@ protected void processArguments() {
 		environment.useTabulations(jsapActualArgs.getBoolean("tabs"));
 		environment.setCopyResources(!jsapActualArgs.getBoolean("no-copy-resources"));
 		environment.setGenerateJavadoc(jsapActualArgs.getBoolean("generate-javadoc"));
+		environment.setCommentEnabled(jsapActualArgs.getBoolean("enable-comments"));
 
 		environment.setShouldCompile(jsapActualArgs.getBoolean("compile"));
 

src/main/java/spoon/compiler/Environment.java

@@ -288,14 +288,28 @@ void report(Processor<?> processor, Level level,
 
 	/**
 	 * Returns the value of the option generate-javadoc.
+	 *
+	 * @see #isCommentsEnabled()
 	 */
+	@Deprecated
 	boolean isGenerateJavadoc();
 
 	/**
 	 * Sets the option generate-javadoc to generate javadoc of the project on the source generated.
 	 */
+	@Deprecated
 	void setGenerateJavadoc(boolean generateJavadoc);
 
+	/**
+	 * Returns the value of the option enable-comments.
+	 */
+	boolean isCommentsEnabled();
+
+	/**
+	 * Sets the option enable-comments to parse comments of the target project.
+	 */
+	void setCommentEnabled(boolean commentEnabled);
+
 	/**
 	 * Gets the factory of the environment.
 	 */

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

@@ -1116,7 +1116,7 @@ public <T> void visitCtSuperAccess(CtSuperAccess<T> f) {
 
 	@Override
 	public void visitCtComment(CtComment comment) {
-		if (!env.isGenerateJavadoc() && context.elementStack.size() > 1) {
+		if (!env.isGenerateJavadoc() && !env.isCommentsEnabled() && context.elementStack.size() > 1) {
 			return;
 		}
 		switch (comment.getCommentType()) {
@@ -1595,15 +1595,15 @@ public DefaultJavaPrettyPrinter writeThrowsClause(CtExecutable<?> e) {
 	}
 
 	private void printComment(CtComment comment) {
-		if (!env.isGenerateJavadoc() || comment == null) {
+		if (!env.isGenerateJavadoc() || !env.isCommentsEnabled() || comment == null) {
 			return;
 		}
 		scan(comment);
 		writeln().writeTabs();
 	}
 
 	private void printComment(List<CtComment> comments) {
-		if (!env.isGenerateJavadoc() || comments == null) {
+		if (!env.isGenerateJavadoc() || !env.isCommentsEnabled() || comments == null) {
 			return;
 		}
 		for (CtComment comment : comments) {
@@ -1624,7 +1624,7 @@ private void printComment(CtElement e, CommentOffset offset) {
 
 	private List<CtComment> getComments(CtElement e, CommentOffset offset) {
 		List<CtComment> commentsToPrint = new ArrayList<CtComment>();
-		if (!env.isGenerateJavadoc() || e == null) {
+		if (!env.isGenerateJavadoc() || !env.isCommentsEnabled() || e == null) {
 			return commentsToPrint;
 		}
 		for (CtComment comment : e.getComments()) {

src/main/java/spoon/support/StandardEnvironment.java

@@ -91,6 +91,8 @@ public class StandardEnvironment implements Serializable, Environment {
 
 	private boolean generateJavadoc = false;
 
+	private boolean enableComments = false;
+
 	private Logger logger = Logger.getLogger(StandardEnvironment.class);
 
 	private Level level = Level.OFF;
@@ -493,4 +495,14 @@ public boolean isGenerateJavadoc() {
 	public void setGenerateJavadoc(boolean generateJavadoc) {
 		this.generateJavadoc = generateJavadoc;
 	}
+
+	@Override
+	public boolean isCommentsEnabled() {
+		return enableComments;
+	}
+
+	@Override
+	public void setCommentEnabled(boolean commentEnabled) {
+		this.enableComments = commentEnabled;
+	}
 }

src/main/java/spoon/support/compiler/jdt/JDTBasedSpoonCompiler.java

@@ -440,7 +440,9 @@ protected boolean buildSources(JDTBuilder jdtBuilder) {
 		for (int i = 0; i < units.length; i++) {
 			CompilationUnitDeclaration unit = units[i];
 			unit.traverse(builder, unit.scope);
-			new JDTCommentBuilder(unit, factory).build();
+			if (getFactory().getEnvironment().isGenerateJavadoc() || getFactory().getEnvironment().isCommentsEnabled()) {
+				new JDTCommentBuilder(unit, factory).build();
+			}
 		}
 
 		return probs.size() == 0;
@@ -489,7 +491,9 @@ protected boolean buildTemplates(JDTBuilder jdtBuilder) {
 		for (int i = 0; i < units.length; i++) {
 			CompilationUnitDeclaration unit = units[i];
 			unit.traverse(builder, unit.scope);
-			new JDTCommentBuilder(unit, factory).build();
+			if (getFactory().getEnvironment().isGenerateJavadoc() || getFactory().getEnvironment().isCommentsEnabled()) {
+				new JDTCommentBuilder(unit, factory).build();
+			}
 		}
 
 		return probs.size() == 0;

src/test/java/spoon/reflect/visitor/CtScannerTest.java

@@ -79,6 +79,7 @@ public Class<CtElement> getType() {
 		final Launcher launcher = new Launcher();
 		launcher.getEnvironment().setNoClasspath(true);
 		launcher.getEnvironment().setGenerateJavadoc(true);
+		launcher.getEnvironment().setCommentEnabled(true);
 		launcher.getEnvironment().useTabulations(true);
 		launcher.setSourceOutputDirectory("./target/generated/");
 		// interfaces.

src/test/java/spoon/test/comment/CommentTest.java

@@ -41,9 +41,10 @@ private Factory getSpoonFactory()  {
 		final Launcher launcher = new Launcher();
 		launcher.run(new String[] {
 				"-i", "./src/test/java/spoon/test/comment/testclasses/",
-				"-o", "./target/spooned/"
+				"-o", "./target/spooned/",
+				"-j",
+				"-c"
 		});
-		launcher.getEnvironment().setGenerateJavadoc(true);
 		return launcher.getFactory();
 	}
 

src/test/java/spoon/test/javadoc/JavaDocTest.java

@@ -1,28 +1,34 @@
 package spoon.test.javadoc;
 
-import org.junit.Assert;
 import org.junit.Test;
 import spoon.Launcher;
 import spoon.SpoonAPI;
+import spoon.reflect.code.CtComment;
 import spoon.reflect.declaration.CtClass;
+import spoon.reflect.declaration.CtElement;
 import spoon.reflect.factory.Factory;
+import spoon.reflect.visitor.CtScanner;
 import spoon.test.javadoc.testclasses.Bar;
 
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.fail;
+
 public class JavaDocTest {
 	@Test
 	public void testJavaDocReprint() throws Exception {
 		SpoonAPI launcher = new Launcher();
 		launcher.getEnvironment().setAutoImports(true);
 		launcher.getEnvironment().setNoClasspath(true);
 		launcher.getEnvironment().setGenerateJavadoc(true);
+		launcher.getEnvironment().setCommentEnabled(true);
 		launcher.getEnvironment().setCopyResources(false);
 		launcher.addInputResource("./src/test/java/spoon/test/javadoc/testclasses/");
 		launcher.setSourceOutputDirectory("./target/spooned/");
 		launcher.run();
 		Factory factory = launcher.getFactory();
 		CtClass<?> aClass = factory.Class().get(Bar.class);
 
-		Assert.assertEquals("public class Bar {" + System.lineSeparator()
+		assertEquals("public class Bar {" + System.lineSeparator()
 				+ "    /**" + System.lineSeparator()
 				+ "     * Creates an annotation type." + System.lineSeparator()
 				+ "     * " + System.lineSeparator()
@@ -36,4 +42,31 @@ public void testJavaDocReprint() throws Exception {
 				+ "    }" + System.lineSeparator()
 				+ "}", aClass.toString());
 	}
+
+	@Test
+	public void testJavadocNotPresentInAST() throws Exception {
+		SpoonAPI launcher = new Launcher();
+		launcher.getEnvironment().setGenerateJavadoc(false);
+		launcher.getEnvironment().setCommentEnabled(false);
+		launcher.getEnvironment().setNoClasspath(true);
+		launcher.addInputResource("./src/test/java/spoon/test/javadoc/testclasses/");
+		launcher.setSourceOutputDirectory("./target/trash/");
+		launcher.run();
+
+		new CtScanner() {
+			@Override
+			public void scan(CtElement element) {
+				if (element != null) {
+					assertEquals(0, element.getComments().size());
+				}
+				super.scan(element);
+			}
+
+			@Override
+			public void visitCtComment(CtComment comment) {
+				fail("Shouldn't have comment in the model.");
+				super.visitCtComment(comment);
+			}
+		}.scan(launcher.getModel().getRootPackage());
+	}
 }