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 1fab454ef0501571d575ae6fb0c8367fd03f8a85
Author: Gary Gregory <gardgreg...@gmail.com>
AuthorDate: Mon Sep 9 10:57:17 2019 -0400

    Javadoc and better param names.
---
 .../org/apache/bcel/classfile/LocalVariable.java   | 39 +++++++--------
 .../org/apache/bcel/generic/LocalVariableGen.java  |  6 +--
 .../bcel/verifier/statics/LocalVariableInfo.java   | 57 +++++++++++++---------
 .../bcel/verifier/statics/LocalVariablesInfo.java  | 25 +++++++---
 .../bcel/verifier/structurals/LocalVariables.java  | 50 ++++++++++++-------
 .../bcel/verifier/structurals/Subroutine.java      | 16 +++---
 6 files changed, 115 insertions(+), 78 deletions(-)

diff --git a/src/main/java/org/apache/bcel/classfile/LocalVariable.java 
b/src/main/java/org/apache/bcel/classfile/LocalVariable.java
index f8100cf..7ad67e4 100644
--- a/src/main/java/org/apache/bcel/classfile/LocalVariable.java
+++ b/src/main/java/org/apache/bcel/classfile/LocalVariable.java
@@ -45,7 +45,7 @@ public final class LocalVariable implements Cloneable, Node, 
Constants {
     // Technically, a decscriptor_index for a local variable table entry
     // and a signature_index for a local variable type table entry.
     private int signature_index; // Index of variable signature
-    private int index; /* Variable is `index'th local variable on
+    private int index; /* Variable is index'th local variable on
      * this method's frame.
      */
     private ConstantPool constant_pool;
@@ -53,18 +53,19 @@ public final class LocalVariable implements Cloneable, 
Node, Constants {
 
 
     /**
-     * Initialize from another object. Note that both objects use the same
+     * Initializes from another LocalVariable. Note that both objects use the 
same
      * references (shallow copy). Use copy() for a physical copy.
+     *
+     * @param localVariable Another LocalVariable.
      */
-    public LocalVariable(final LocalVariable c) {
-        this(c.getStartPC(), c.getLength(), c.getNameIndex(), 
c.getSignatureIndex(), c.getIndex(),
-                c.getConstantPool());
-        this.orig_index = c.getOrigIndex();
+    public LocalVariable(final LocalVariable localVariable) {
+        this(localVariable.getStartPC(), localVariable.getLength(), 
localVariable.getNameIndex(),
+                localVariable.getSignatureIndex(), localVariable.getIndex(), 
localVariable.getConstantPool());
+        this.orig_index = localVariable.getOrigIndex();
     }
 
-
     /**
-     * Construct object from file stream.
+     * Constructs object from file stream.
      * @param file Input stream
      * @throws IOException
      */
@@ -129,20 +130,20 @@ public final class LocalVariable implements Cloneable, 
Node, Constants {
 
 
     /**
-     * Dump local variable to file stream in binary format.
+     * Dumps local variable to file stream in binary format.
      *
-     * @param file Output file stream
-     * @throws IOException
+     * @param dataOutputStream Output file stream
+     * @exception IOException if an I/O error occurs.
+     * @see java.io.FilterOutputStream#out
      */
-    public void dump( final DataOutputStream file ) throws IOException {
-        file.writeShort(start_pc);
-        file.writeShort(length);
-        file.writeShort(name_index);
-        file.writeShort(signature_index);
-        file.writeShort(index);
+    public void dump(final DataOutputStream dataOutputStream) throws 
IOException {
+        dataOutputStream.writeShort(start_pc);
+        dataOutputStream.writeShort(length);
+        dataOutputStream.writeShort(name_index);
+        dataOutputStream.writeShort(signature_index);
+        dataOutputStream.writeShort(index);
     }
 
-
     /**
      * @return Constant pool used by this object.
      */
@@ -212,7 +213,7 @@ public final class LocalVariable implements Cloneable, 
Node, Constants {
 
 
     /**
-     * @return Start of range where he variable is valid
+     * @return Start of range where the variable is valid
      */
     public int getStartPC() {
         return start_pc;
diff --git a/src/main/java/org/apache/bcel/generic/LocalVariableGen.java 
b/src/main/java/org/apache/bcel/generic/LocalVariableGen.java
index b7722af..d2316df 100644
--- a/src/main/java/org/apache/bcel/generic/LocalVariableGen.java
+++ b/src/main/java/org/apache/bcel/generic/LocalVariableGen.java
@@ -21,7 +21,7 @@ import org.apache.bcel.Const;
 import org.apache.bcel.classfile.LocalVariable;
 
 /**
- * This class represents a local variable within a method. It contains its
+ * Represents a local variable within a method. It contains its
  * scope, name and type. The generated LocalVariable object can be obtained
  * with getLocalVariable which needs the instruction list and the constant
  * pool as parameters.
@@ -66,7 +66,7 @@ public class LocalVariableGen implements InstructionTargeter, 
NamedAndTyped, Clo
 
 
     /**
-     * Generate a local variable that with index `index'. Note that double and 
long
+     * Generates a local variable that with index `index'. Note that double 
and long
      * variables need two indexs. Index indices have to be provided by the 
user.
      *
      * @param index index of local variable
@@ -84,7 +84,7 @@ public class LocalVariableGen implements InstructionTargeter, 
NamedAndTyped, Clo
 
 
     /**
-     * Get LocalVariable object.
+     * Gets LocalVariable object.
      *
      * This relies on that the instruction list has already been dumped to 
byte code or
      * or that the `setPositions' methods has been called for the instruction 
list.
diff --git 
a/src/main/java/org/apache/bcel/verifier/statics/LocalVariableInfo.java 
b/src/main/java/org/apache/bcel/verifier/statics/LocalVariableInfo.java
index 9779cc8..3db76d6 100644
--- a/src/main/java/org/apache/bcel/verifier/statics/LocalVariableInfo.java
+++ b/src/main/java/org/apache/bcel/verifier/statics/LocalVariableInfo.java
@@ -28,12 +28,12 @@ import 
org.apache.bcel.verifier.exc.LocalVariableInfoInconsistentException;
  * the name and the type of a local variable in
  * a given slot (== index). This information
  * often changes in course of byte code offsets.
- *
  */
 public class LocalVariableInfo{
 
     /** The types database. KEY: String representing the offset integer. */
     private final Hashtable<String, Type> types = new Hashtable<>();
+
     /** The names database. KEY: String representing the offset integer. */
     private final Hashtable<String, String> names = new Hashtable<>();
 
@@ -44,6 +44,7 @@ public class LocalVariableInfo{
     private void setName(final int offset, final String name) {
         names.put(Integer.toString(offset), name);
     }
+
     /**
      * Adds a type of a local variable and a certain slot to our 'types'
      * (Hashtable) database.
@@ -53,54 +54,64 @@ public class LocalVariableInfo{
     }
 
     /**
-     * Returns the type of the local variable that uses this local
-     * variable slot at the given bytecode offset.
-     * Care for legal bytecode offsets yourself, otherwise the return value
-     * might be wrong.
-     * May return 'null' if nothing is known about the type of this local
-     * variable slot at the given bytecode offset.
+     * Returns the type of the local variable that uses this local variable 
slot at the given bytecode offset. Care for
+     * legal bytecode offsets yourself, otherwise the return value might be 
wrong. May return 'null' if nothing is known
+     * about the type of this local variable slot at the given bytecode offset.
+     *
+     * @param offset bytecode offset.
+     * @return the type of the local variable that uses this local variable 
slot at the given bytecode offset.
      */
     public Type getType(final int offset) {
         return types.get(Integer.toString(offset));
     }
+
     /**
-     * Returns the name of the local variable that uses this local
-     * variable slot at the given bytecode offset.
-     * Care for legal bytecode offsets yourself, otherwise the return value
-     * might be wrong.
-     * May return 'null' if nothing is known about the type of this local
-     * variable slot at the given bytecode offset.
+     * Returns the name of the local variable that uses this local variable 
slot at the given bytecode offset. Care for
+     * legal bytecode offsets yourself, otherwise the return value might be 
wrong. May return 'null' if nothing is known
+     * about the type of this local variable slot at the given bytecode offset.
+     *
+     * @param offset bytecode offset.
+     * @return the name of the local variable that uses this local variable 
slot at the given bytecode offset.
      */
     public String getName(final int offset) {
         return names.get(Integer.toString(offset));
     }
+
     /**
      * Adds some information about this local variable (slot).
+     *
+     * @param name variable name
+     * @param startPc Range in which the variable is valid.
+     * @param length length of ...
+     * @param type variable type
+     *
      * @throws LocalVariableInfoInconsistentException if the new information 
conflicts
      *         with already gathered information.
      */
-    public void add(final String name, final int startpc, final int length, 
final Type t) throws LocalVariableInfoInconsistentException{
-        for (int i=startpc; i<=startpc+length; i++) { // incl/incl-notation!
-            add(i,name,t);
+    public void add(final String name, final int startPc, final int length, 
final Type type)
+            throws LocalVariableInfoInconsistentException {
+        for (int i = startPc; i <= startPc + length; i++) { // 
incl/incl-notation!
+            add(i, name, type);
         }
     }
 
     /**
      * Adds information about name and type for a given offset.
+     *
      * @throws LocalVariableInfoInconsistentException if the new information 
conflicts
      *         with already gathered information.
      */
-    private void add(final int offset, final String name, final Type t) throws 
LocalVariableInfoInconsistentException{
+    private void add(final int offset, final String name, final Type t) throws 
LocalVariableInfoInconsistentException {
         if (getName(offset) != null) {
-            if (! getName(offset).equals(name)) {
-                throw new LocalVariableInfoInconsistentException("At bytecode 
offset '"+offset+
-                    "' a local variable has two different names: 
'"+getName(offset)+"' and '"+name+"'.");
+            if (!getName(offset).equals(name)) {
+                throw new LocalVariableInfoInconsistentException("At bytecode 
offset '" + offset
+                        + "' a local variable has two different names: '" + 
getName(offset) + "' and '" + name + "'.");
             }
         }
         if (getType(offset) != null) {
-            if (! getType(offset).equals(t)) {
-                throw new LocalVariableInfoInconsistentException("At bytecode 
offset '"+offset+
-                    "' a local variable has two different types: 
'"+getType(offset)+"' and '"+t+"'.");
+            if (!getType(offset).equals(t)) {
+                throw new LocalVariableInfoInconsistentException("At bytecode 
offset '" + offset
+                        + "' a local variable has two different types: '" + 
getType(offset) + "' and '" + t + "'.");
             }
         }
         setName(offset, name);
diff --git 
a/src/main/java/org/apache/bcel/verifier/statics/LocalVariablesInfo.java 
b/src/main/java/org/apache/bcel/verifier/statics/LocalVariablesInfo.java
index 14479e7..069efa6 100644
--- a/src/main/java/org/apache/bcel/verifier/statics/LocalVariablesInfo.java
+++ b/src/main/java/org/apache/bcel/verifier/statics/LocalVariablesInfo.java
@@ -26,7 +26,6 @@ import 
org.apache.bcel.verifier.exc.LocalVariableInfoInconsistentException;
  * A utility class holding the information about
  * the names and the types of the local variables in
  * a given method.
- *
  */
 public class LocalVariablesInfo{
 
@@ -41,7 +40,12 @@ public class LocalVariablesInfo{
         }
     }
 
-    /** Returns the LocalVariableInfo for the given slot. */
+    /**
+     * Returns the LocalVariableInfo for the given slot.
+     *
+     * @param slot Slot to query.
+     * @return The LocalVariableInfo for the given slot.
+     */
     public LocalVariableInfo getLocalVariableInfo(final int slot) {
         if (slot < 0 || slot >= localVariableInfos.length) {
             throw new AssertionViolatedException("Slot number for local 
variable information out of range.");
@@ -52,22 +56,27 @@ public class LocalVariablesInfo{
     /**
      * Adds information about the local variable in slot 'slot'. Automatically
      * adds information for slot+1 if 't' is Type.LONG or Type.DOUBLE.
+     *
+     * @param name variable name
+     * @param startPc Range in which the variable is valid.
+     * @param length length of ...
+     * @param type variable type
      * @throws LocalVariableInfoInconsistentException if the new information 
conflicts
      *         with already gathered information.
      */
-    public void add(final int slot, final String name, final int startpc, 
final int length, final Type t) throws LocalVariableInfoInconsistentException{
+    public void add(final int slot, final String name, final int startPc, 
final int length, final Type type) throws 
LocalVariableInfoInconsistentException{
         // The add operation on LocalVariableInfo may throw the 
'...Inconsistent...' exception, we don't throw it explicitely here.
 
         if (slot < 0 || slot >= localVariableInfos.length) {
             throw new AssertionViolatedException("Slot number for local 
variable information out of range.");
         }
 
-        localVariableInfos[slot].add(name, startpc, length, t);
-        if (t == Type.LONG) {
-            localVariableInfos[slot+1].add(name, startpc, length, 
LONG_Upper.theInstance());
+        localVariableInfos[slot].add(name, startPc, length, type);
+        if (type == Type.LONG) {
+            localVariableInfos[slot+1].add(name, startPc, length, 
LONG_Upper.theInstance());
         }
-        if (t == Type.DOUBLE) {
-            localVariableInfos[slot+1].add(name, startpc, length, 
DOUBLE_Upper.theInstance());
+        if (type == Type.DOUBLE) {
+            localVariableInfos[slot+1].add(name, startPc, length, 
DOUBLE_Upper.theInstance());
         }
     }
 }
diff --git 
a/src/main/java/org/apache/bcel/verifier/structurals/LocalVariables.java 
b/src/main/java/org/apache/bcel/verifier/structurals/LocalVariables.java
index fd3b237..f884749 100644
--- a/src/main/java/org/apache/bcel/verifier/structurals/LocalVariables.java
+++ b/src/main/java/org/apache/bcel/verifier/structurals/LocalVariables.java
@@ -29,15 +29,18 @@ import 
org.apache.bcel.verifier.exc.StructuralCodeConstraintException;
  *
  */
 public class LocalVariables implements Cloneable {
+
     /** The Type[] containing the local variable slots. */
     private final Type[] locals;
 
     /**
      * Creates a new LocalVariables object.
+     *
+     * @param localVariableCount local variable count.
      */
-    public LocalVariables(final int maxLocals) {
-        locals = new Type[maxLocals];
-        for (int i=0; i<maxLocals; i++) {
+    public LocalVariables(final int localVariableCount) {
+        locals = new Type[localVariableCount];
+        for (int i=0; i<localVariableCount; i++) {
             locals[i] = Type.UNKNOWN;
         }
     }
@@ -57,23 +60,29 @@ public class LocalVariables implements Cloneable {
     }
 
     /**
-     * Returns the type of the local variable slot i.
+     * Returns the type of the local variable slot index.
+     *
+     * @param slotIndex Slot to look up.
+     * @return the type of the local variable slot index.
      */
-    public Type get(final int i) {
-        return locals[i];
+    public Type get(final int slotIndex) {
+        return locals[slotIndex];
     }
 
     /**
      * Returns a (correctly typed) clone of this object.
      * This is equivalent to ((LocalVariables) this.clone()).
+     *
+     * @return a (correctly typed) clone of this object.
      */
     public LocalVariables getClone() {
         return (LocalVariables) this.clone();
     }
 
     /**
-     * Returns the number of local variable slots this
-     * LocalVariables instance has.
+     * Returns the number of local variable slots.
+     *
+     * @return the number of local variable slots.
      */
     public int maxLocals() {
         return locals.length;
@@ -81,12 +90,15 @@ public class LocalVariables implements Cloneable {
 
     /**
      * Sets a new Type for the given local variable slot.
+     *
+     * @param slotIndex Target slot index.
+     * @param type Type to save at the given slot index.
      */
-    public void set(final int i, final Type type) { // TODO could be 
package-protected?
+    public void set(final int slotIndex, final Type type) { // TODO could be 
package-protected?
         if (type == Type.BYTE || type == Type.SHORT || type == Type.BOOLEAN || 
type == Type.CHAR) {
             throw new AssertionViolatedException("LocalVariables do not know 
about '"+type+"'. Use Type.INT instead.");
         }
-        locals[i] = type;
+        locals[slotIndex] = type;
     }
 
     /** @return a hash code value for the object.
@@ -118,15 +130,17 @@ public class LocalVariables implements Cloneable {
     /**
      * Merges two local variables sets as described in the Java Virtual 
Machine Specification,
      * Second Edition, section 4.9.2, page 146.
+     *
+     * @param localVariable other local variable.
      */
-    public void merge(final LocalVariables lv) {
+    public void merge(final LocalVariables localVariable) {
 
-        if (this.locals.length != lv.locals.length) {
+        if (this.locals.length != localVariable.locals.length) {
             throw new AssertionViolatedException("Merging LocalVariables of 
different size?!? From different methods or what?!?");
         }
 
         for (int i=0; i<locals.length; i++) {
-            merge(lv, i);
+            merge(localVariable, i);
         }
     }
 
@@ -204,13 +218,15 @@ public class LocalVariables implements Cloneable {
     }
 
     /**
-     * Replaces all occurences of u in this local variables set
+     * Replaces all occurrences of {@code uninitializedObjectType} in this 
local variables set
      * with an "initialized" ObjectType.
+     *
+     * @param uninitializedObjectType the object to match.
      */
-    public void initializeObject(final UninitializedObjectType u) {
+    public void initializeObject(final UninitializedObjectType 
uninitializedObjectType) {
         for (int i=0; i<locals.length; i++) {
-            if (locals[i] == u) {
-                locals[i] = u.getInitialized();
+            if (locals[i] == uninitializedObjectType) {
+                locals[i] = uninitializedObjectType.getInitialized();
             }
         }
     }
diff --git a/src/main/java/org/apache/bcel/verifier/structurals/Subroutine.java 
b/src/main/java/org/apache/bcel/verifier/structurals/Subroutine.java
index ee6cffd..ea60415 100644
--- a/src/main/java/org/apache/bcel/verifier/structurals/Subroutine.java
+++ b/src/main/java/org/apache/bcel/verifier/structurals/Subroutine.java
@@ -22,13 +22,13 @@ import org.apache.bcel.generic.InstructionHandle;
 /**
  * This interface defines properties of JVM bytecode subroutines. Note that it 
is 'abused' to maintain the top-level
  * code in a consistent fashion, too.
- *
  */
 public interface Subroutine {
+
     /**
      * Returns all the JsrInstructions that have the first instruction of this 
subroutine as their target. <B>Must not
      * be invoked on the 'top-level subroutine'.</B>
-     * 
+     *
      * @return The JsrInstructions that have the first instruction of this 
subroutine as their target.
      */
     InstructionHandle[] getEnteringJsrInstructions();
@@ -36,7 +36,7 @@ public interface Subroutine {
     /**
      * Returns the one and only RET that leaves the subroutine. Note that 
JustIce has a pretty rigid notion of a
      * subroutine. <B>Must not be invoked on the 'top-level subroutine'.</B>
-     * 
+     *
      * @return The one and only RET that leaves the subroutine.
      *
      * @see Subroutines
@@ -47,7 +47,7 @@ public interface Subroutine {
      * Returns all instructions that together form this subroutine. Note that 
an instruction is part of exactly one
      * subroutine (the top-level code is considered to be a special 
subroutine) - else it is not reachable at all (dead
      * code).
-     * 
+     *
      * @return All instructions that together form this subroutine.
      */
     InstructionHandle[] getInstructions();
@@ -55,7 +55,7 @@ public interface Subroutine {
     /**
      * Returns if the given InstructionHandle refers to an instruction that is 
part of this subroutine. This is a
      * convenience method that saves iteration over the InstructionHandle 
objects returned by getInstructions().
-     * 
+     *
      * @param inst The InstructionHandle to test.
      * @return Whether the given InstructionHandle refers to an instruction 
that is part of this subroutine.
      *
@@ -66,7 +66,7 @@ public interface Subroutine {
     /**
      * Returns an int[] containing the indices of the local variable slots 
accessed by this Subroutine (read-accessed,
      * write-accessed or both); local variables referenced by subroutines of 
this subroutine are not included.
-     * 
+     *
      * @return An int[] containing the indices of the local variable slots.
      * @see #getRecursivelyAccessedLocalsIndices()
      */
@@ -75,7 +75,7 @@ public interface Subroutine {
     /**
      * Returns an int[] containing the indices of the local variable slots 
accessed by this Subroutine (read-accessed,
      * write-accessed or both); local variables referenced by subroutines of 
this subroutine are included.
-     * 
+     *
      * @return An int[] containing the indices of the local variable slots.
      * @see #getAccessedLocalsIndices()
      */
@@ -83,7 +83,7 @@ public interface Subroutine {
 
     /**
      * Returns the subroutines that are directly called from this subroutine.
-     * 
+     *
      * @return The subroutines that are directly called from this subroutine.
      */
     Subroutine[] subSubs();

Reply via email to