doc: Fix issues related to javadoc in java 8

* Javadoc JDK8: start fixing issues #1104

* Fix last javadoc errors for JDK8 #1104

* Fix failing tests in CtComment by decoding html entities in snippets. Add necessary dependency to do that properly. #1104

* Fix the scope of the new dependency

pom.xml

@@ -241,6 +241,12 @@
       <artifactId>commons-io</artifactId>
       <version>1.4</version>
     </dependency>
+    <dependency>
+      <groupId>org.apache.commons</groupId>
+      <artifactId>commons-lang3</artifactId>
+      <version>3.5</version>
+      <scope>test</scope>
+    </dependency>
   </dependencies>
 
   <build>

src/main/java/spoon/SpoonModelBuilder.java

@@ -81,8 +81,8 @@ public interface SpoonModelBuilder {
 	boolean build(JDTBuilder builder);
 
 	/** The types of compilable elements
-	 * FILES - compiles the java files from the file system, which were registered by {@see SpoonModelBuilder#addInputSource()} and {@see SpoonModelBuilder#addTemplateSource(File)}
-	 * CTTYPES - compiles virtual java files, which are dynamically generated from the all top level classes of the CtModel by {@see DefaultJavaPrettyPrinter}
+	 * FILES - compiles the java files from the file system, which were registered by {@link #addInputSource(File)} and {@link #addTemplateSource(File)}
+	 * CTTYPES - compiles virtual java files, which are dynamically generated from the all top level classes of the CtModel by {@link spoon.reflect.visitor.DefaultJavaPrettyPrinter}
 	 */
 	interface InputType {
 		InputType FILES = FileCompilerConfig.INSTANCE;

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

@@ -23,7 +23,7 @@
  * <pre>
  *     int[] array = new int[10];
  *     System.out.println(
- *     array[0] // <-- array read
+ *     array[0] // &lt;-- array read
  *     );
  * </pre>
  *

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

@@ -22,7 +22,7 @@
  * Example:
  * <pre>
  *     int x;
- *     x = 4; // <-- an assignment
+ *     x = 4; // &lt;-- an assignment
  * </pre>
  * @param <T>
  * 		type of assigned expression

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

@@ -24,7 +24,7 @@
  * statements enclosed in curly brackets.
  *
  * Example: <pre>
- *  { // <-- block start
+ *  { // &lt;-- block start
  *   System.out.println("foo");
  *  }
  *	</pre>

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

@@ -20,9 +20,9 @@
  * This code element defines a break statement.
  * Example:
  * <pre>
- *     for(int i=0; i<10; i++) {
- *         if (i>3) {
- *				break; // <-- break statement
+ *     for(int i=0; i&lt;10; i++) {
+ *         if (i&gt;3) {
+ *				break; // &lt;-- break statement
  *         }
  *     }
  * </pre>

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

@@ -22,7 +22,7 @@
  * Example: <pre>
  * int x = 0;
  * switch(x) {
- *     case 1: // <-- case statement
+ *     case 1: // &lt;-- case statement
  *       System.out.println("foo");
  * }</pre>
  *

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

@@ -22,7 +22,7 @@
  * Example:
  * <pre>
  *     System.out.println(
- *        1==0 ? "foo" : "bar" // <-- ternary conditional
+ *        1==0 ? "foo" : "bar" // &lt;-- ternary conditional
  *     );
  * </pre>
  */

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

@@ -20,9 +20,9 @@
  * This code element defines the continue statement.
  * Example:
  * <pre>
- *     for(int i=0; i<10; i++) {
- *         if (i>3) {
- *				continue; // <-- continue statement
+ *     for(int i=0; i&lt;10; i++) {
+ *         if (i&gt;3) {
+ *				continue; // &lt;-- continue statement
  *         }
  *     }
  * </pre>

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

@@ -24,7 +24,7 @@
  *     int x = 0;
  *     do {
  *         x=x+1;
- *     } while (x<10);
+ *     } while (x&lt;10);
  * </pre>
  *
  */

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

@@ -23,7 +23,7 @@
  * Example:
  * <pre>
  *     // a for statement
- *     for(int i=0; i<10; i++) {
+ *     for(int i=0; i&lt;10; i++) {
  *     	System.out.println("foo");
  *     }
  * </pre>

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

@@ -21,7 +21,7 @@
  * Example:
  * <pre>
  *     java.util.List l = new java.util.ArrayList();
- *     for(Object o : l) { // <-- foreach loop
+ *     for(Object o : l) { // &lt;-- foreach loop
  *     	System.out.println(o);
  *     }
  * </pre>

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

@@ -30,7 +30,7 @@
  * <pre>
  *     java.util.List l = new java.util.ArrayList();
  *     l.stream().map(
- *       x -> { return x.toString(); } // a lambda
+ *       x -&gt; { return x.toString(); } // a lambda
  *     );
  * </pre>
  *

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

@@ -31,7 +31,7 @@
  * <pre>
  *    // an anonymous class creation
  *    Runnable r = new Runnable() {
- *     	@Override
+ *     	&#64;Override
  *     	public void run() {
  *     	  System.out.println("foo");
  *     	}

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

@@ -22,7 +22,7 @@
  * Example:
  * <pre>
  *     int x = 0;
- *     x *= 3; // <-- a CtOperatorAssignment
+ *     x *= 3; // &lt;-- a CtOperatorAssignment
  * </pre>
  *
  */

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

@@ -24,9 +24,9 @@
  * Example:
  * <pre>
  *    Runnable r = new Runnable() {
- *     	@Override
+ *     	&#64;Override
  *     	public void run() {
- *     	  return; // <-- CtReturn statement
+ *     	  return; // &lt;-- CtReturn statement
  *     	}
  *    };
  * </pre>

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

@@ -27,7 +27,7 @@
  *     class Foo { int foo() { return 42;}};
  *     class Bar extends Foo {
  *     int foo() {
- *       return super.foo(); // <-- access to super
+ *       return super.foo(); // &lt;-- access to super
  *     }
  *     };
  * </pre>

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

@@ -23,7 +23,7 @@
  *
  * Example: <pre>
  * int x = 0;
- * switch(x) { // <-- switch statement
+ * switch(x) { // &lt;-- switch statement
  *     case 1:
  *       System.out.println("foo");
  * }</pre>

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

@@ -24,7 +24,7 @@
  *     class Foo {
  *     int value = 42;
  *     int foo() {
- *       return this.value; // <-- access to this
+ *       return this.value; // &lt;-- access to this
  *     }
  *     };
 

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

@@ -21,7 +21,7 @@
  * For example :
  * <pre>
  *     int x=3;
- *     --x; // <-- unary --
+ *     --x; // &lt;-- unary --
  * </pre>
  *
  * @param <T>

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

@@ -23,7 +23,7 @@
  * <pre>
  *     String variable = "";
  *     System.out.println(
- *       variable // <-- a variable read
+ *       variable // &lt;-- a variable read
  *     );
  * </pre>
  *

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

@@ -33,8 +33,8 @@
  *
  * <pre>
  *     // statement annotated by annotation @SuppressWarnings
- *     @SuppressWarnings("unchecked")
- *     java.util.List<?> x = new java.util.ArrayList<>()
+ *     &#64;SuppressWarnings("unchecked")
+ *     java.util.List&lt;?&gt; x = new java.util.ArrayList&lt;&gt;()
  * </pre>
  * @param <A>
  * 		type of represented annotation

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

@@ -166,7 +166,7 @@ public interface Factory {
 	<R> CtStatementList createStatementList(CtBlock<R> block);
 
 	/**
-	 *  @see CodeFactory#createCtBlock(T)
+	 *  @see CodeFactory#createCtBlock(CtStatement)
 	 */
 	<T extends CtStatement> CtBlock<?> createCtBlock(T element);
 
@@ -206,7 +206,7 @@ public interface Factory {
 	<T> CtInvocation<T> createInvocation(CtExpression<?> target, CtExecutableReference<T> executable, CtExpression<?>... arguments);
 
 	/**
-	 *  @see CodeFactory#createLiteral(T)
+	 *  @see CodeFactory#createLiteral(Object)
 	 */
 	<T> CtLiteral<T> createLiteral(T value);
 
@@ -216,7 +216,7 @@ public interface Factory {
 	<T> CtLocalVariable<T> createLocalVariable(CtTypeReference<T> type, String name, CtExpression<T> defaultExpression);
 
 	/**
-	 *  @see CodeFactory#createLiteralArray(T[])
+	 *  @see CodeFactory#createLiteralArray(Object[])
 	 */
 	@SuppressWarnings(value = "unchecked")
 	<T> CtNewArray<T[]> createLiteralArray(T[] value);

src/main/java/spoon/reflect/visitor/chain/CtFunction.java

@@ -21,8 +21,8 @@
  * It is used in the query stack, for example by {@link CtQueryable#map(CtFunction)}
  * Compatible with Java 8 lambdas, hence enable to write queries with lambdas.
  *
- * @param <T> the type of the input to the function
- * @param <R> the type of the result of the function
+ * @param <T> the type of the input to the function
+ * @param <R> the type of the result of the function
  */
 public interface CtFunction<T, R> {
 	R apply(T input);

src/main/java/spoon/reflect/visitor/chain/CtQuery.java

@@ -29,8 +29,8 @@
  *
  * The main methods are:
  * <ul>
- * <li> {@link #map(CtFunction))} - uses a lambda expression to return any model elements that are directly accessible from an input element.
- * <li> {@link #filterChildren(Filter))} - uses {@link Filter} instances to filter children of an element
+ * <li> {@link CtQueryable#map(CtFunction)} - uses a lambda expression to return any model elements that are directly accessible from an input element.
+ * <li> {@link CtQueryable#filterChildren(Filter)} - uses {@link Filter} instances to filter children of an element
  * <li> {@link #list()} - to evaluate the query and return a list of elements produced by this query.
  * </ul>
  * The query can be used several times.<br>
@@ -39,7 +39,7 @@
  * However, reusing a {@link CtQuery} instance makes sense when the same query has to be evaluated
  * several times in a loop.
  *
- * @param &lt;O> the type of the element produced by this query
+ * @param <O> the type of the element produced by this query
  */
 public interface CtQuery<O> extends CtQueryable {
 

src/main/java/spoon/reflect/visitor/chain/CtQueryable.java

@@ -29,7 +29,7 @@ public interface CtQueryable {
 
 	/**
 	 * Query elements based on a function, the behavior depends on the return type of the function.
-	 * <table>
+	 * <table summary="">
 	 * <tr><td><b>Return type of `function`</b><td><b>Behavior</b>
 	 * <tr><td>{@link Boolean}<td>Select elements if thereturned value of `function` is true (as for {@link Filter}).
 	 * <tr><td>? extends {@link Object}<td>Send the returned value of `function` to the next step

src/main/java/spoon/reflect/visitor/filter/AbstractReferenceFilter.java

@@ -25,7 +25,7 @@
  *
  * @param <T>
  * 		the type of the reference to be matched
- * @see spoon.reflect.visitor.ReferenceFilter#matches(CtReference)
+ * @see spoon.reflect.visitor.Filter
  *
  * @deprecated use {@link AbstractFilter} instead.
  */

src/main/java/spoon/support/reflect/eval/VisitorPartialEvaluator.java

@@ -58,7 +58,7 @@
 
 /**
  *
- * Simplifies an AST by performing all operations that are statically known and changes the AST accordingly (eg "0+1" -> "1")
+ * Simplifies an AST by performing all operations that are statically known and changes the AST accordingly (eg "0+1" -> "1")
  * This visitor implements a simple partial evaluator for the program
  * compile-time metamodel.
  */

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

@@ -1,6 +1,7 @@
 package spoon.test.comment;
 
 import org.apache.commons.io.IOUtils;
+import org.apache.commons.lang3.StringEscapeUtils;
 import org.junit.Test;
 import spoon.Launcher;
 import spoon.reflect.code.CtComment;
@@ -626,6 +627,7 @@ public boolean matches(CtElement element) {
 				m.find();
 				do {
 					String snippet = m.group(1);
+					snippet = StringEscapeUtils.unescapeHtml4(snippet);
 
 					// it must compile
 					CtElement el = launcher.getFactory().Code().createCodeSnippetStatement(snippet).compile();