From a31616c9032a3da43982f50cafb6f34d67030c03 Mon Sep 17 00:00:00 2001 From: Eric Bruneton Date: Sat, 27 Aug 2022 16:37:14 +0200 Subject: Improve the Javadoc for the InnerClasses and EnclosingMethod attributes. --- .../java/org/objectweb/asm/tree/ClassNode.java | 17 ++++++++---- .../org/objectweb/asm/tree/InnerClassNode.java | 32 +++++++++++++--------- .../main/java/org/objectweb/asm/ClassVisitor.java | 31 +++++++++++++-------- 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) { -- cgit v1.2.3