This is an automated email from the ASF dual-hosted git repository. ggregory pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-bcel.git
commit 0f8dedc0a3817a2aa9ae9d2348c30af5e63385f4 Author: Gary Gregory <[email protected]> AuthorDate: Fri Jan 9 14:46:16 2026 -0500 Javadoc --- .../apache/bcel/generic/AnnotationEntryGen.java | 53 ++++++++++++++++++++++ .../apache/bcel/generic/ArithmeticInstruction.java | 4 +- .../apache/bcel/generic/ArrayElementValueGen.java | 38 ++++++++++++++-- .../java/org/apache/bcel/generic/ArrayType.java | 12 +++-- src/main/java/org/apache/bcel/generic/BIPUSH.java | 4 +- .../java/org/apache/bcel/generic/BasicType.java | 7 +++ .../bcel/generic/ConstantPushInstruction.java | 5 ++ .../org/apache/bcel/generic/ElementValueGen.java | 5 ++ .../org/apache/bcel/generic/ReferenceType.java | 14 ++++-- .../org/apache/bcel/generic/ReturnInstruction.java | 4 +- .../org/apache/bcel/generic/StoreInstruction.java | 8 ++-- src/main/java/org/apache/bcel/generic/Type.java | 20 ++++++-- 12 files changed, 156 insertions(+), 18 deletions(-) diff --git a/src/main/java/org/apache/bcel/generic/AnnotationEntryGen.java b/src/main/java/org/apache/bcel/generic/AnnotationEntryGen.java index 0e66dbe4..fa343f46 100644 --- a/src/main/java/org/apache/bcel/generic/AnnotationEntryGen.java +++ b/src/main/java/org/apache/bcel/generic/AnnotationEntryGen.java @@ -201,6 +201,15 @@ public class AnnotationEntryGen { return null; } + /** + * Reads an AnnotationEntryGen from a DataInput. + * + * @param dis the data input stream. + * @param cpool the constant pool generator. + * @param b whether the annotation is runtime visible. + * @return the annotation entry generator. + * @throws IOException if an I/O error occurs. + */ public static AnnotationEntryGen read(final DataInput dis, final ConstantPoolGen cpool, final boolean b) throws IOException { final AnnotationEntryGen a = new AnnotationEntryGen(cpool); a.typeIndex = dis.readUnsignedShort(); @@ -246,6 +255,14 @@ public class AnnotationEntryGen { this.cpool = cpool; } + /** + * Constructs an AnnotationEntryGen. + * + * @param type the object type. + * @param elements the element value pairs. + * @param vis whether the annotation is visible. + * @param cpool the constant pool generator. + */ public AnnotationEntryGen(final ObjectType type, final List<ElementValuePairGen> elements, final boolean vis, final ConstantPoolGen cpool) { this.cpool = cpool; this.typeIndex = cpool.addUtf8(type.getSignature()); @@ -253,6 +270,11 @@ public class AnnotationEntryGen { isRuntimeVisible = vis; } + /** + * Adds an element name value pair. + * + * @param evp the element value pair generator. + */ public void addElementNameValuePair(final ElementValuePairGen evp) { if (evs == null) { evs = new ArrayList<>(); @@ -264,6 +286,12 @@ public class AnnotationEntryGen { return Streams.of(in).map(nvp -> new ElementValuePairGen(nvp, cpool, copyPoolEntries)).collect(Collectors.toList()); } + /** + * Dumps this annotation entry to a DataOutputStream. + * + * @param dos the data output stream. + * @throws IOException if an I/O error occurs. + */ public void dump(final DataOutputStream dos) throws IOException { dos.writeShort(typeIndex); // u2 index of type name in cpool dos.writeShort(evs.size()); // u2 element_value pair count @@ -285,15 +313,30 @@ public class AnnotationEntryGen { return a; } + /** + * Gets the type index. + * + * @return the type index. + */ public int getTypeIndex() { return typeIndex; } + /** + * Gets the type name. + * + * @return the type name. + */ public final String getTypeName() { return getTypeSignature(); // BCELBUG: Should I use this instead? // Utility.signatureToString(getTypeSignature()); } + /** + * Gets the type signature. + * + * @return the type signature. + */ public final String getTypeSignature() { // ConstantClass c = (ConstantClass) cpool.getConstant(typeIndex); final ConstantUtf8 utf8 = (ConstantUtf8) cpool.getConstant(typeIndex/* c.getNameIndex() */); @@ -309,6 +352,11 @@ public class AnnotationEntryGen { return evs; } + /** + * Gets whether this annotation is runtime visible. + * + * @return true if this annotation is runtime visible. + */ public boolean isRuntimeVisible() { return isRuntimeVisible; } @@ -317,6 +365,11 @@ public class AnnotationEntryGen { isRuntimeVisible = b; } + /** + * Returns a short string representation of this annotation. + * + * @return a short string representation of this annotation. + */ public String toShortString() { final StringBuilder s = new StringBuilder(); s.append("@").append(getTypeName()).append("("); diff --git a/src/main/java/org/apache/bcel/generic/ArithmeticInstruction.java b/src/main/java/org/apache/bcel/generic/ArithmeticInstruction.java index 32bb93c2..797be007 100644 --- a/src/main/java/org/apache/bcel/generic/ArithmeticInstruction.java +++ b/src/main/java/org/apache/bcel/generic/ArithmeticInstruction.java @@ -32,7 +32,9 @@ public abstract class ArithmeticInstruction extends Instruction implements Typed } /** - * @param opcode of instruction + * Constructs an ArithmeticInstruction. + * + * @param opcode of instruction. */ protected ArithmeticInstruction(final short opcode) { super(opcode, (short) 1); diff --git a/src/main/java/org/apache/bcel/generic/ArrayElementValueGen.java b/src/main/java/org/apache/bcel/generic/ArrayElementValueGen.java index ace560e1..27496f18 100644 --- a/src/main/java/org/apache/bcel/generic/ArrayElementValueGen.java +++ b/src/main/java/org/apache/bcel/generic/ArrayElementValueGen.java @@ -39,8 +39,11 @@ public class ArrayElementValueGen extends ElementValueGen { private final List<ElementValueGen> evalues; /** - * @param value - * @param cpool + * Constructs an ArrayElementValueGen. + * + * @param value the array element value. + * @param cpool the constant pool generator. + * @param copyPoolEntries whether to copy pool entries. */ public ArrayElementValueGen(final ArrayElementValue value, final ConstantPoolGen cpool, final boolean copyPoolEntries) { super(ARRAY, cpool); @@ -51,11 +54,23 @@ public class ArrayElementValueGen extends ElementValueGen { } } + /** + * Constructs an ArrayElementValueGen. + * + * @param cp the constant pool generator. + */ public ArrayElementValueGen(final ConstantPoolGen cp) { super(ARRAY, cp); evalues = new ArrayList<>(); } + /** + * Constructs an ArrayElementValueGen. + * + * @param type the type. + * @param elementValues the element values. + * @param cpool the constant pool generator. + */ public ArrayElementValueGen(final int type, final ElementValue[] elementValues, final ConstantPoolGen cpool) { super(type, cpool); if (type != ARRAY) { @@ -64,6 +79,11 @@ public class ArrayElementValueGen extends ElementValueGen { this.evalues = Streams.of(elementValues).map(e -> copy(e, cpool, true)).collect(Collectors.toList()); } + /** + * Adds an element. + * + * @param gen the element value generator. + */ public void addElement(final ElementValueGen gen) { evalues.add(gen); } @@ -78,7 +98,9 @@ public class ArrayElementValueGen extends ElementValueGen { } /** - * Return immutable variant of this ArrayElementValueGen + * Return immutable variant of this ArrayElementValueGen. + * + * @return immutable variant of this ArrayElementValueGen. */ @Override public ElementValue getElementValue() { @@ -90,10 +112,20 @@ public class ArrayElementValueGen extends ElementValueGen { return new ArrayElementValue(super.getElementValueType(), immutableData, getConstantPool().getConstantPool()); } + /** + * Gets the element values. + * + * @return the element values. + */ public List<ElementValueGen> getElementValues() { return evalues; } + /** + * Gets the element values size. + * + * @return the element values size. + */ public int getElementValuesSize() { return evalues.size(); } diff --git a/src/main/java/org/apache/bcel/generic/ArrayType.java b/src/main/java/org/apache/bcel/generic/ArrayType.java index f76e9a64..05267e59 100644 --- a/src/main/java/org/apache/bcel/generic/ArrayType.java +++ b/src/main/java/org/apache/bcel/generic/ArrayType.java @@ -93,7 +93,9 @@ public final class ArrayType extends ReferenceType { } /** - * @return basic type of array, i.e., for int[][][] the basic type is int + * Gets the basic type of array, i.e., for int[][][] the basic type is int. + * + * @return basic type of array, i.e., for int[][][] the basic type is int. */ public Type getBasicType() { return basicType; @@ -111,14 +113,18 @@ public final class ArrayType extends ReferenceType { } /** - * @return number of dimensions of array + * Gets the number of dimensions of array. + * + * @return number of dimensions of array. */ public int getDimensions() { return dimensions; } /** - * @return element type of array, i.e., for int[][][] the element type is int[][] + * Gets the element type of array, i.e., for int[][][] the element type is int[][]. + * + * @return element type of array, i.e., for int[][][] the element type is int[][]. */ public Type getElementType() { if (dimensions == 1) { diff --git a/src/main/java/org/apache/bcel/generic/BIPUSH.java b/src/main/java/org/apache/bcel/generic/BIPUSH.java index a118ac15..40c9378f 100644 --- a/src/main/java/org/apache/bcel/generic/BIPUSH.java +++ b/src/main/java/org/apache/bcel/generic/BIPUSH.java @@ -41,7 +41,9 @@ public class BIPUSH extends Instruction implements ConstantPushInstruction { } /** - * Push byte on stack + * Push byte on stack. + * + * @param b the byte value to push. */ public BIPUSH(final byte b) { super(org.apache.bcel.Const.BIPUSH, (short) 2); diff --git a/src/main/java/org/apache/bcel/generic/BasicType.java b/src/main/java/org/apache/bcel/generic/BasicType.java index 3963c4f0..a7407866 100644 --- a/src/main/java/org/apache/bcel/generic/BasicType.java +++ b/src/main/java/org/apache/bcel/generic/BasicType.java @@ -25,6 +25,13 @@ import org.apache.bcel.Const; */ public final class BasicType extends Type { + /** + * Gets the BasicType for the given type constant. + * + * @param type the type constant. + * @return the BasicType. + * @since 6.0 + */ // @since 6.0 no longer final public static BasicType getType(final byte type) { switch (type) { diff --git a/src/main/java/org/apache/bcel/generic/ConstantPushInstruction.java b/src/main/java/org/apache/bcel/generic/ConstantPushInstruction.java index ed904efc..9d16d7fb 100644 --- a/src/main/java/org/apache/bcel/generic/ConstantPushInstruction.java +++ b/src/main/java/org/apache/bcel/generic/ConstantPushInstruction.java @@ -27,5 +27,10 @@ package org.apache.bcel.generic; */ public interface ConstantPushInstruction extends PushInstruction, TypedInstruction { + /** + * Gets the value to be pushed onto the stack. + * + * @return the value to be pushed onto the stack. + */ Number getValue(); } diff --git a/src/main/java/org/apache/bcel/generic/ElementValueGen.java b/src/main/java/org/apache/bcel/generic/ElementValueGen.java index b1dc9d47..635fda5e 100644 --- a/src/main/java/org/apache/bcel/generic/ElementValueGen.java +++ b/src/main/java/org/apache/bcel/generic/ElementValueGen.java @@ -177,5 +177,10 @@ public abstract class ElementValueGen { return type; } + /** + * Returns a string representation of the element value. + * + * @return a string representation of the element value. + */ public abstract String stringifyValue(); } diff --git a/src/main/java/org/apache/bcel/generic/ReferenceType.java b/src/main/java/org/apache/bcel/generic/ReferenceType.java index 05783ae7..f78be865 100644 --- a/src/main/java/org/apache/bcel/generic/ReferenceType.java +++ b/src/main/java/org/apache/bcel/generic/ReferenceType.java @@ -46,6 +46,8 @@ public abstract class ReferenceType extends Type { * interface, then {@link #OBJECT} is returned. If not all of the two classes' superclasses cannot be found, "null" is * returned. See the JVM specification edition 2, "�4.9.2 The Bytecode Verifier". * + * @param t the other type. + * @return the first common superclass. * @throws ClassNotFoundException on failure to find superclasses of this type, or the type passed as a parameter. * @deprecated Use getFirstCommonSuperclass(ReferenceType t) which has slightly changed semantics. */ @@ -79,7 +81,9 @@ public abstract class ReferenceType extends Type { * the two classes' superclasses cannot be found, "null" is returned. See the JVM specification edition 2, "�4.9.2 The * Bytecode Verifier". * - * @throws ClassNotFoundException on failure to find superclasses of this type, or the type passed as a parameter + * @param t the other type. + * @return the first common superclass. + * @throws ClassNotFoundException on failure to find superclasses of this type, or the type passed as a parameter. */ public ReferenceType getFirstCommonSuperclass(final ReferenceType t) throws ClassNotFoundException { if (equals(NULL)) { @@ -148,8 +152,10 @@ public abstract class ReferenceType extends Type { * Return true iff this is assignment compatible with another type t as defined in the JVM specification; see the * AASTORE definition there. * + * @param t the other type. + * @return true iff this is assignment compatible with another type t. * @throws ClassNotFoundException if any classes or interfaces required to determine assignment compatibility can't be - * found + * found. */ public boolean isAssignmentCompatibleWith(final Type t) throws ClassNotFoundException { if (!(t instanceof ReferenceType)) { @@ -247,8 +253,10 @@ public abstract class ReferenceType extends Type { * {@link #NULL} is not defined (see the CHECKCAST definition in the JVM specification). However, because for example CHECKCAST * doesn't throw a ClassCastException when casting a null reference to any Object, true is returned in this case. * + * @param t the other type. + * @return true iff this type is castable to another type t. * @throws ClassNotFoundException if any classes or interfaces required to determine assignment compatibility can't be - * found + * found. */ public boolean isCastableTo(final Type t) throws ClassNotFoundException { if (equals(NULL)) { diff --git a/src/main/java/org/apache/bcel/generic/ReturnInstruction.java b/src/main/java/org/apache/bcel/generic/ReturnInstruction.java index 3ce41f71..50fbeb75 100644 --- a/src/main/java/org/apache/bcel/generic/ReturnInstruction.java +++ b/src/main/java/org/apache/bcel/generic/ReturnInstruction.java @@ -33,7 +33,9 @@ public abstract class ReturnInstruction extends Instruction implements Exception } /** - * @param opcode of instruction + * Constructs a ReturnInstruction. + * + * @param opcode of instruction. */ protected ReturnInstruction(final short opcode) { super(opcode, (short) 1); diff --git a/src/main/java/org/apache/bcel/generic/StoreInstruction.java b/src/main/java/org/apache/bcel/generic/StoreInstruction.java index f9647b08..4eaa2757 100644 --- a/src/main/java/org/apache/bcel/generic/StoreInstruction.java +++ b/src/main/java/org/apache/bcel/generic/StoreInstruction.java @@ -32,9 +32,11 @@ public abstract class StoreInstruction extends LocalVariableInstruction implemen } /** - * @param opcode Instruction opcode - * @param cTag Instruction number for compact version, ASTORE_0, for example - * @param n local variable index (unsigned short) + * Constructs a StoreInstruction. + * + * @param opcode Instruction opcode. + * @param cTag Instruction number for compact version, ASTORE_0, for example. + * @param n local variable index (unsigned short). */ protected StoreInstruction(final short opcode, final short cTag, final int n) { super(opcode, cTag, n); diff --git a/src/main/java/org/apache/bcel/generic/Type.java b/src/main/java/org/apache/bcel/generic/Type.java index 91ec9aa1..a406efc5 100644 --- a/src/main/java/org/apache/bcel/generic/Type.java +++ b/src/main/java/org/apache/bcel/generic/Type.java @@ -346,11 +346,18 @@ public abstract class Type { return false; } + /** + * Gets the class name. + * + * @return the class name. + */ public String getClassName() { return toString(); } /** + * Gets the signature for this type. + * * @return signature for given type. */ public String getSignature() { @@ -358,7 +365,9 @@ public abstract class Type { } /** - * @return stack size of this type (2 for long and double, 0 for void, 1 otherwise) + * Gets the stack size of this type. + * + * @return stack size of this type (2 for long and double, 0 for void, 1 otherwise). */ public int getSize() { switch (type) { @@ -373,14 +382,18 @@ public abstract class Type { } /** - * @return type as defined in Constants + * Gets the type as defined in Constants. + * + * @return type as defined in Constants. */ public byte getType() { return type; } /** - * @return hash code of Type + * Gets the hash code of this Type. + * + * @return hash code of Type. */ @Override public int hashCode() { @@ -391,6 +404,7 @@ public abstract class Type { * boolean, short and char variable are considered as int in the stack or local variable area. Returns {@link #INT} * for {@link #BOOLEAN}, {@link #SHORT} or {@link #CHAR}, otherwise returns the given type. * + * @return the normalized type. * @since 6.0 */ public Type normalizeForStackOrLocal() {
