Improve the Javadoc for the InnerClasses and EnclosingMethod attributes.

3 files changed, 50 insertions, 30 deletions

diff --git a/asm-tree/src/main/java/org/objectweb/asm/tree/ClassNode.java b/asm-tree/src/main/java/org/objectweb/asm/tree/ClassNode.java
index 8821581d..a9f362c1 100644
--- a/asm-tree/src/main/java/org/objectweb/asm/tree/ClassNode.java
+++ b/asm-tree/src/main/java/org/objectweb/asm/tree/ClassNode.java
@@ -88,18 +88,25 @@ public class ClassNode extends ClassVisitor {
   /** The module stored in this class. May be {@literal null}. */
   public ModuleNode module;
 
-  /** The internal name of the enclosing class of this class. May be {@literal null}. */
+  /**
+   * The internal name of the enclosing class of this class. Must be {@literal null} if this class
+   * has no enclosing class, or if it is a local or anonymous class.
+   */
   public String outerClass;
 
   /**
-   * The name of the method that contains this class, or {@literal null} if this class is not
-   * enclosed in a method.
+   * The name of the method that contains the class, or {@literal null} if the class has no
+   * enclosing class, or is not enclosed in a method or constructor of its enclosing class (e.g. if
+   * it is enclosed in an instance initializer, static initializer, instance variable initializer,
+   * or class variable initializer).
    */
   public String outerMethod;
 
   /**
-   * The descriptor of the method that contains this class, or {@literal null} if this class is not
-   * enclosed in a method.
+   * The descriptor of the method that contains the class, or {@literal null} if the class has no
+   * enclosing class, or is not enclosed in a method or constructor of its enclosing class (e.g. if
+   * it is enclosed in an instance initializer, static initializer, instance variable initializer,
+   * or class variable initializer).
    */
   public String outerMethodDesc;
 
diff --git a/asm-tree/src/main/java/org/objectweb/asm/tree/InnerClassNode.java b/asm-tree/src/main/java/org/objectweb/asm/tree/InnerClassNode.java
index a996afa4..ca9101b6 100644
--- a/asm-tree/src/main/java/org/objectweb/asm/tree/InnerClassNode.java
+++ b/asm-tree/src/main/java/org/objectweb/asm/tree/InnerClassNode.java
@@ -30,7 +30,11 @@ package org.objectweb.asm.tree;
 import org.objectweb.asm.ClassVisitor;
 
 /**
- * A node that represents an inner class.
+ * A node that represents an inner class. This inner class is not necessarily a member of the {@link
+ * ClassNode} containing this object. More precisely, every class or interface C which is referenced
+ * by a {@link ClassNode} and which is not a package member must be represented with an {@link
+ * InnerClassNode}. The {@link ClassNode} must reference its nested class or interface members, and
+ * its enclosing class, if any. See the JVMS 4.7.6 section for more details.
  *
  * @author Eric Bruneton
  */
@@ -46,25 +50,27 @@ public class InnerClassNode {
   public String outerName;
 
   /**
-   * The (simple) name of the inner class inside its enclosing class. May be {@literal null} for
-   * anonymous inner classes.
+   * The (simple) name of the inner class inside its enclosing class. Must be {@literal null} if the
+   * inner class is not the member of a class or interface (e.g. for local or anonymous classes).
    */
   public String innerName;
 
-  /** The access flags of the inner class as originally declared in the enclosing class. */
+  /**
+   * The access flags of the inner class as originally declared in the source code from which the
+   * class was compiled.
+   */
   public int access;
 
   /**
-   * Constructs a new {@link InnerClassNode}.
+   * Constructs a new {@link InnerClassNode} for an inner class C.
    *
-   * @param name the internal name of an inner class (see {@link
-   *     org.objectweb.asm.Type#getInternalName()}).
-   * @param outerName the internal name of the class to which the inner class belongs (see {@link
-   *     org.objectweb.asm.Type#getInternalName()}). May be {@literal null}.
-   * @param innerName the (simple) name of the inner class inside its enclosing class. May be
-   *     {@literal null} for anonymous inner classes.
-   * @param access the access flags of the inner class as originally declared in the enclosing
-   *     class.
+   * @param name the internal name of C (see {@link org.objectweb.asm.Type#getInternalName()}).
+   * @param outerName the internal name of the class or interface C is a member of (see {@link
+   *     org.objectweb.asm.Type#getInternalName()}). Must be {@literal null} if C is not the member
+   *     of a class or interface (e.g. for local or anonymous classes).
+   * @param innerName the (simple) name of C. Must be {@literal null} for anonymous inner classes.
+   * @param access the access flags of C originally declared in the source code from which this
+   *     class was compiled.
    */
   public InnerClassNode(
       final String name, final String outerName, final String innerName, final int access) {
diff --git a/asm/src/main/java/org/objectweb/asm/ClassVisitor.java b/asm/src/main/java/org/objectweb/asm/ClassVisitor.java
index 7ba37505..a557f9e4 100644
--- a/asm/src/main/java/org/objectweb/asm/ClassVisitor.java
+++ b/asm/src/main/java/org/objectweb/asm/ClassVisitor.java
@@ -169,14 +169,18 @@ public abstract class ClassVisitor {
   }
 
   /**
-   * Visits the enclosing class of the class. This method must be called only if the class has an
-   * enclosing class.
+   * Visits the enclosing class of the class. This method must be called only if this class is a
+   * local or anonymous class. See the JVMS 4.7.7 section for more details.
    *
    * @param owner internal name of the enclosing class of the class.
    * @param name the name of the method that contains the class, or {@literal null} if the class is
-   *     not enclosed in a method of its enclosing class.
+   *     not enclosed in a method or constructor of its enclosing class (e.g. if it is enclosed in
+   *     an instance initializer, static initializer, instance variable initializer, or class
+   *     variable initializer).
    * @param descriptor the descriptor of the method that contains the class, or {@literal null} if
-   *     the class is not enclosed in a method of its enclosing class.
+   *     the class is not enclosed in a method or constructor of its enclosing class (e.g. if it is
+   *     enclosed in an instance initializer, static initializer, instance variable initializer, or
+   *     class variable initializer).
    */
   public void visitOuterClass(final String owner, final String name, final String descriptor) {
     if (cv != null) {
@@ -271,15 +275,18 @@ public abstract class ClassVisitor {
 
   /**
    * Visits information about an inner class. This inner class is not necessarily a member of the
-   * class being visited.
+   * class being visited. More precisely, every class or interface C which is referenced by this
+   * class and which is not a package member must be visited with this method. This class must
+   * reference its nested class or interface members, and its enclosing class, if any. See the JVMS
+   * 4.7.6 section for more details.
    *
-   * @param name the internal name of an inner class (see {@link Type#getInternalName()}).
-   * @param outerName the internal name of the class to which the inner class belongs (see {@link
-   *     Type#getInternalName()}). May be {@literal null} for not member classes.
-   * @param innerName the (simple) name of the inner class inside its enclosing class. May be
-   *     {@literal null} for anonymous inner classes.
-   * @param access the access flags of the inner class as originally declared in the enclosing
-   *     class.
+   * @param name the internal name of C (see {@link Type#getInternalName()}).
+   * @param outerName the internal name of the class or interface C is a member of (see {@link
+   *     Type#getInternalName()}). Must be {@literal null} if C is not the member of a class or
+   *     interface (e.g. for local or anonymous classes).
+   * @param innerName the (simple) name of C. Must be {@literal null} for anonymous inner classes.
+   * @param access the access flags of C originally declared in the source code from which this
+   *     class was compiled.
    */
   public void visitInnerClass(
       final String name, final String outerName, final String innerName, final int access) {