* Document some nodes

* Make all "Empty..." nodes deprecated

javaparser-core/src/main/java/com/github/javaparser/Problem.java

@@ -24,7 +24,7 @@ public String toString() {
         if (cause != null) {
             str.append(" stack : ").append(System.lineSeparator());
             for (StackTraceElement ste : cause.getStackTrace())
-                str.append(ste.toString());
+                str.append(ste.toString()).append(System.lineSeparator());
         }
         return str.toString();
     }

javaparser-core/src/main/java/com/github/javaparser/ast/body/AnnotationDeclaration.java

@@ -32,6 +32,8 @@
 import java.util.EnumSet;
 
 /**
+ * <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-9.html#jls-9.6">JLS</a>
+ * An annotation type declaration: <code>@interface X { ... }</code>
  * @author Julio Vilmar Gesser
  */
 public final class AnnotationDeclaration extends TypeDeclaration<AnnotationDeclaration> {

javaparser-core/src/main/java/com/github/javaparser/ast/body/AnnotationMemberDeclaration.java

@@ -44,6 +44,8 @@
 import static com.github.javaparser.utils.Utils.assertNotNull;
 
 /**
+ * <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-9.html#jls-AnnotationTypeElementDeclaration">JLS</a> 
+ * The "int id();" in <code>@interface X { int id(); }</code>
  * @author Julio Vilmar Gesser
  */
 public final class AnnotationMemberDeclaration extends BodyDeclaration<AnnotationMemberDeclaration> implements

javaparser-core/src/main/java/com/github/javaparser/ast/body/BodyDeclaration.java

@@ -34,6 +34,7 @@
 import static com.github.javaparser.utils.Utils.assertNotNull;
 
 /**
+ * Any declaration that can appear between the { and } of a class, interface, or enum.
  * @author Julio Vilmar Gesser
  */
 public abstract class BodyDeclaration<T extends Node> extends Node implements NodeWithAnnotations<T> {

javaparser-core/src/main/java/com/github/javaparser/ast/body/ClassOrInterfaceDeclaration.java

@@ -42,6 +42,8 @@
 import static com.github.javaparser.utils.Utils.assertNotNull;
 
 /**
+ * <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#jls-8.1">JLS</a>
+ * A definition of a class or interface. <code>class X { ... }</code>
  * @author Julio Vilmar Gesser
  */
 public final class ClassOrInterfaceDeclaration extends TypeDeclaration<ClassOrInterfaceDeclaration> implements

javaparser-core/src/main/java/com/github/javaparser/ast/body/ConstructorDeclaration.java

@@ -43,6 +43,8 @@
 import static com.github.javaparser.utils.Utils.assertNotNull;
 
 /**
+ * <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#jls-8.8">JLS</a>
+ * A constructor declaration: <code>class X { X() { } }</code> where X(){} is the constructor declaration.
  * @author Julio Vilmar Gesser
  */
 public final class ConstructorDeclaration extends BodyDeclaration<ConstructorDeclaration> implements

javaparser-core/src/main/java/com/github/javaparser/ast/body/EmptyMemberDeclaration.java

@@ -29,8 +29,11 @@
 import com.github.javaparser.ast.visitor.VoidVisitor;
 
 /**
+ * A loose ";" inside a body. <code>class X { ; }</code>
  * @author Julio Vilmar Gesser
+ * @deprecated these ;'s should be ignored
  */
+@Deprecated
 public final class EmptyMemberDeclaration extends BodyDeclaration<EmptyMemberDeclaration>
         implements NodeWithJavaDoc<EmptyMemberDeclaration> {
 

javaparser-core/src/main/java/com/github/javaparser/ast/body/EnumConstantDeclaration.java

@@ -40,6 +40,8 @@
 import static com.github.javaparser.utils.Utils.assertNotNull;
 
 /**
+ * <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#jls-8.9.1">JLS</a>
+ * One of the values an enum can take. A(1) and B(2) in this example: <code>enum X { A(1), B(2) }</code>
  * @author Julio Vilmar Gesser
  */
 public final class EnumConstantDeclaration extends BodyDeclaration<EnumConstantDeclaration> implements

javaparser-core/src/main/java/com/github/javaparser/ast/body/EnumDeclaration.java

@@ -39,6 +39,8 @@
 import static com.github.javaparser.utils.Utils.assertNotNull;
 
 /**
+ * <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#jls-8.9">JLS</a>
+ * The declaration of an enum. <code>enum X { ... }</code>
  * @author Julio Vilmar Gesser
  */
 public final class EnumDeclaration extends TypeDeclaration<EnumDeclaration> implements

javaparser-core/src/main/java/com/github/javaparser/ast/body/FieldDeclaration.java

@@ -49,6 +49,8 @@
 import static com.github.javaparser.utils.Utils.assertNotNull;
 
 /**
+ * <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#jls-8.3">JLS</a>
+ * The declaration of a field in a class. "private static int a=15*15;" in this example: <code>class X { private static int a=15*15; }</code>
  * @author Julio Vilmar Gesser
  */
 public final class FieldDeclaration extends BodyDeclaration<FieldDeclaration> implements

javaparser-core/src/main/java/com/github/javaparser/ast/body/InitializerDeclaration.java

@@ -33,6 +33,8 @@
 import static com.github.javaparser.utils.Utils.assertNotNull;
 
 /**
+ * <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#jls-8.6">JLS</a>
+ * A (possibly static) initializer block. "static { a=3; }" in this example: <code>class X { static { a=3; }  } </code> 
  * @author Julio Vilmar Gesser
  */
 public final class InitializerDeclaration extends BodyDeclaration<InitializerDeclaration>

javaparser-core/src/main/java/com/github/javaparser/ast/body/MethodDeclaration.java

@@ -46,6 +46,8 @@
 import static com.github.javaparser.utils.Utils.assertNotNull;
 
 /**
+ * <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#jls-8.4">JLS</a>
+ * A method declaration. "public int abc() {return 1;}" in this example: <code>class X { public int abc() {return 1;} }</code>
  * @author Julio Vilmar Gesser
  */
 public final class MethodDeclaration extends BodyDeclaration<MethodDeclaration> implements

javaparser-core/src/main/java/com/github/javaparser/ast/body/Parameter.java

@@ -41,6 +41,10 @@
 import static com.github.javaparser.utils.Utils.assertNotNull;
 
 /**
+ * <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#jls-8.4.1">JLS</a>
+ * The parameters to a method or lambda. Lambda parameters may have inferred types, in that case "type" is UnknownType.
+ * Note that <a href="https://en.wikipedia.org/wiki/Parameter_(computer_programming)#Parameters_and_arguments">parameters are different from arguments.</a> 
+ * "String x" and "float y" are the parameters in <code>int abc(String x, float y) {...}</code>
  * @author Julio Vilmar Gesser
  */
 public final class Parameter extends Node implements

javaparser-core/src/main/java/com/github/javaparser/ast/body/TypeDeclaration.java

@@ -41,6 +41,7 @@
 import static com.github.javaparser.utils.Utils.assertNotNull;
 
 /**
+ * A base class for all types of type declarations.
  * @author Julio Vilmar Gesser
  */
 public abstract class TypeDeclaration<T extends Node> extends BodyDeclaration<T> implements

javaparser-core/src/main/java/com/github/javaparser/ast/body/VariableDeclarator.java

@@ -38,6 +38,9 @@
 import static com.github.javaparser.utils.Utils.assertNotNull;
 
 /**
+ * <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-14.html#jls-14.4">JLS</a>
+ * The declaration of a variable. <code>int x = 14;</code>
+ *
  * @author Julio Vilmar Gesser
  */
 public final class VariableDeclarator extends Node implements

javaparser-core/src/main/java/com/github/javaparser/ast/stmt/EmptyStmt.java

@@ -27,7 +27,9 @@
 
 /**
  * @author Julio Vilmar Gesser
+ * @deprecated these ;'s should be ignored
  */
+@Deprecated
 public final class EmptyStmt extends Statement {
 
     public EmptyStmt() {

javaparser-core/src/main/java/com/github/javaparser/ast/stmt/TypeDeclarationStmt.java

@@ -22,7 +22,7 @@
 package com.github.javaparser.ast.stmt;
 
 import com.github.javaparser.Range;
-import com.github.javaparser.ast.body.EmptyTypeDeclaration;
+import com.github.javaparser.ast.body.ClassOrInterfaceDeclaration;
 import com.github.javaparser.ast.body.TypeDeclaration;
 import com.github.javaparser.ast.observing.ObservableProperty;
 import com.github.javaparser.ast.visitor.GenericVisitor;
@@ -38,7 +38,7 @@ public final class TypeDeclarationStmt extends Statement {
     private TypeDeclaration typeDecl;
 
     public TypeDeclarationStmt() {
-        this(null, new EmptyTypeDeclaration());
+        this(null, new ClassOrInterfaceDeclaration());
     }
 
     public TypeDeclarationStmt(final TypeDeclaration typeDecl) {

javaparser-core/src/main/java/com/github/javaparser/ast/visitor/CloneVisitor.java

@@ -119,17 +119,6 @@ public Visitable visit(EnumDeclaration _n, Object _arg) {
         return r;
     }
 
-    @Override
-    public Visitable visit(EmptyTypeDeclaration _n, Object _arg) {
-        Comment comment = cloneNode(_n.getComment(), _arg);
-
-        EmptyTypeDeclaration r = new EmptyTypeDeclaration(
-                _n.getRange().orElse(null)
-        );
-        r.setComment(comment);
-        return r;
-    }
-
     @Override
     public Visitable visit(EnumConstantDeclaration _n, Object _arg) {
         NodeList<AnnotationExpr> annotations = cloneList(_n.getAnnotations(), _arg);

javaparser-core/src/main/java/com/github/javaparser/ast/visitor/EqualsVisitor.java

@@ -279,11 +279,6 @@ public Boolean visit(final EnumDeclaration n1, final Visitable arg) {
         return true;
     }
 
-    @Override
-    public Boolean visit(final EmptyTypeDeclaration n1, final Visitable arg) {
-        return true;
-    }
-
     @Override
     public Boolean visit(final EnumConstantDeclaration n1, final Visitable arg) {
         final EnumConstantDeclaration n2 = (EnumConstantDeclaration) arg;

javaparser-core/src/main/java/com/github/javaparser/ast/visitor/GenericVisitor.java

@@ -56,8 +56,6 @@ public interface GenericVisitor<R, A> {
 
     R visit(EnumDeclaration n, A arg);
 
-    R visit(EmptyTypeDeclaration n, A arg);
-
     R visit(EnumConstantDeclaration n, A arg);
 
     R visit(AnnotationDeclaration n, A arg);

javaparser-core/src/main/java/com/github/javaparser/ast/visitor/GenericVisitorAdapter.java

@@ -528,12 +528,6 @@ public R visit(final EmptyStmt n, final A arg) {
         return null;
     }
 
-    @Override
-    public R visit(final EmptyTypeDeclaration n, final A arg) {
-        visitComment(n, arg);
-        return null;
-    }
-
     @Override
     public R visit(final EnclosedExpr n, final A arg) {
         visitComment(n, arg);

javaparser-core/src/main/java/com/github/javaparser/ast/visitor/ModifierVisitor.java

@@ -306,12 +306,6 @@ public Visitable visit(final EmptyStmt n, final A arg) {
         return n;
     }
 
-    @Override
-    public Visitable visit(final EmptyTypeDeclaration n, final A arg) {
-        visitComment(n, arg);
-        return n;
-    }
-
     @Override
     public Visitable visit(final EnclosedExpr n, final A arg) {
         visitComment(n, arg);

javaparser-core/src/main/java/com/github/javaparser/ast/visitor/VoidVisitor.java

@@ -21,7 +21,10 @@
 
 package com.github.javaparser.ast.visitor;
 
-import com.github.javaparser.ast.*;
+import com.github.javaparser.ast.ArrayCreationLevel;
+import com.github.javaparser.ast.CompilationUnit;
+import com.github.javaparser.ast.NodeList;
+import com.github.javaparser.ast.PackageDeclaration;
 import com.github.javaparser.ast.body.*;
 import com.github.javaparser.ast.comments.BlockComment;
 import com.github.javaparser.ast.comments.JavadocComment;
@@ -56,8 +59,6 @@ public interface VoidVisitor<A> {
 
     void visit(EnumDeclaration n, A arg);
 
-    void visit(EmptyTypeDeclaration n, A arg);
-
     void visit(EnumConstantDeclaration n, A arg);
 
     void visit(AnnotationDeclaration n, A arg);

javaparser-core/src/main/java/com/github/javaparser/ast/visitor/VoidVisitorAdapter.java

@@ -270,12 +270,6 @@ public void visit(final EmptyStmt n, final A arg) {
         visitComment(n.getComment(), arg);
     }
 
-    @Override
-    public void visit(final EmptyTypeDeclaration n, final A arg) {
-        visitComment(n.getComment(), arg);
-        n.getName().accept(this, arg);
-    }
-
     @Override
     public void visit(final EnclosedExpr n, final A arg) {
         visitComment(n.getComment(), arg);

javaparser-core/src/main/java/com/github/javaparser/printer/PrettyPrintVisitor.java

@@ -259,14 +259,6 @@ public void visit(final ClassOrInterfaceDeclaration n, final Void arg) {
         printer.print("}");
     }
 
-    @Override
-    public void visit(final EmptyTypeDeclaration n, final Void arg) {
-        printJavaComment(n.getComment(), arg);
-        printer.print(";");
-
-        printOrphanCommentsEnding(n);
-    }
-
     @Override
     public void visit(final JavadocComment n, final Void arg) {
         printer.print("/**");