Style fixes and javadoc additions

Author: Aca-S

compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/java/dataflow/AbstractFrame.java

@@ -48,14 +48,28 @@ public class AbstractFrame<T> {
     private final OperandStack<T> operandStack;
     private final LocalVariableTable<T> localVariableTable;
 
+    /**
+     * Get the operand stack of this abstract frame.
+     */
     public OperandStack<T> operandStack() {
         return operandStack;
     }
 
+    /**
+     * Get the local variable table of this abstract frame.
+     */
     public LocalVariableTable<T> localVariableTable() {
         return localVariableTable;
     }
 
+    /**
+     * Transform the chosen values in the abstract frame. This affects both the values on the
+     * operand stack and in the local variable table.
+     *
+     * @param filterFunction Values which satisfy this predicate are subject to transformation with
+     *            {@code transformFunction}.
+     * @param transformFunction The transformation function.
+     */
     public void transform(Predicate<T> filterFunction, Function<T, T> transformFunction) {
         operandStack.transform(filterFunction, transformFunction);
         localVariableTable.transform(filterFunction, transformFunction);
@@ -95,31 +109,53 @@ public int hashCode() {
 
     @Override
     public String toString() {
-        return operandStack + "" + localVariableTable;
+        return operandStack + System.lineSeparator() + localVariableTable;
     }
 
+    /**
+     * Abstract representation of a bytecode operand stack.
+     */
     public static final class OperandStack<T> {
 
         /*
          * An ArrayList is used in order to allow for efficient lookups at arbitrary stack
          * positions, as well as to preserve memory in comparison to allocating a plain array with a
          * max stack size.
          */
-        private final ArrayList<SizedValue<T>> stack;
+        private final ArrayList<ValueWithSlots<T>> stack;
 
+        /**
+         * Get a value at the specified depth of the operand stack. The {@code depth} does not take
+         * into account the size of values, i.e., a {@link ValueWithSlots} with size equal to
+         * {@link ValueWithSlots.Slots#TWO_SLOTS TWO_SLOTS} contributes only as one value to the
+         * depth of the operand stack.
+         */
         public T getOperand(int depth) {
             return peek(depth).value;
         }
 
+        /**
+         * Get the number of values currently on the operand stack. This does not take into account
+         * the size of values, i.e., a {@link ValueWithSlots} with size equal to
+         * {@link ValueWithSlots.Slots#TWO_SLOTS TWO_SLOTS} contributes only as one value for this
+         * method.
+         */
         public int size() {
             return stack.size();
         }
 
+        /**
+         * Transform the chosen values on the operand stack.
+         *
+         * @param filterFunction Values which satisfy this predicate are subject to transformation
+         *            with {@code transformFunction}.
+         * @param transformFunction The transformation function.
+         */
         public void transform(Predicate<T> filterFunction, Function<T, T> transformFunction) {
             for (int i = 0; i < stack.size(); i++) {
-                SizedValue<T> value = stack.get(i);
+                ValueWithSlots<T> value = stack.get(i);
                 if (filterFunction.test(value.value())) {
-                    stack.set(i, new SizedValue<>(transformFunction.apply(value.value()), value.size()));
+                    stack.set(i, new ValueWithSlots<>(transformFunction.apply(value.value()), value.size()));
                 }
             }
         }
@@ -132,21 +168,21 @@ public void transform(Predicate<T> filterFunction, Function<T, T> transformFunct
             this.stack = new ArrayList<>(stack.stack);
         }
 
-        void push(SizedValue<T> value) {
+        void push(ValueWithSlots<T> value) {
             stack.add(value);
         }
 
-        SizedValue<T> pop() {
+        ValueWithSlots<T> pop() {
             GraalError.guarantee(!stack.isEmpty(), "Cannot pop from empty stack");
             return stack.removeLast();
         }
 
-        SizedValue<T> peek(int depth) {
-            GraalError.guarantee(depth < size(), "Operand stack doesn't contain enough values");
+        ValueWithSlots<T> peek(int depth) {
+            GraalError.guarantee(0 <= depth && depth < size(), "Operand stack doesn't contain enough values");
             return stack.get(stack.size() - depth - 1);
         }
 
-        SizedValue<T> peek() {
+        ValueWithSlots<T> peek() {
             return peek(0);
         }
 
@@ -157,10 +193,10 @@ void clear() {
         void mergeWith(OperandStack<T> other, BiFunction<T, T, T> mergeFunction) {
             GraalError.guarantee(size() == other.size(), "Operand stack size must match upon merging");
             for (int i = 0; i < stack.size(); i++) {
-                SizedValue<T> thisValue = stack.get(i);
-                SizedValue<T> thatValue = other.stack.get(i);
+                ValueWithSlots<T> thisValue = stack.get(i);
+                ValueWithSlots<T> thatValue = other.stack.get(i);
                 GraalError.guarantee(thisValue.size() == thatValue.size(), "The size of operand stack values must match upon merging");
-                SizedValue<T> mergedValue = new SizedValue<>(mergeFunction.apply(thisValue.value(), thatValue.value()), thisValue.size());
+                ValueWithSlots<T> mergedValue = new ValueWithSlots<>(mergeFunction.apply(thisValue.value(), thatValue.value()), thisValue.size());
                 stack.set(i, mergedValue);
             }
         }
@@ -186,30 +222,48 @@ public int hashCode() {
         public String toString() {
             StringBuilder builder = new StringBuilder();
             builder.append("Operand stack:\n");
-            for (SizedValue<T> value : stack.reversed()) {
-                builder.append("[").append(value.value()).append("]").append("\n");
+            for (ValueWithSlots<T> value : stack.reversed()) {
+                builder.append("[").append(value.value()).append("]").append(System.lineSeparator());
             }
             return builder.toString();
         }
     }
 
+    /**
+     * Abstract representation of a bytecode local variable table.
+     */
     public static final class LocalVariableTable<T> {
 
-        private final Map<Integer, SizedValue<T>> variables;
+        private final Map<Integer, ValueWithSlots<T>> variables;
 
+        /**
+         * Get the value at the {@code index} slot of the local variable table. The {@code index}
+         * must be valid, i.e., must be in the set which would be returned by
+         * {@link #getVariableIndices()}.
+         */
         public T getVariable(int index) {
             return get(index).value;
         }
 
+        /**
+         * Get the local variable table indices of entries currently stored in it.
+         */
         public Set<Integer> getVariableIndices() {
             return variables.keySet();
         }
 
+        /**
+         * Transform the chosen values in the local variable table.
+         *
+         * @param filterFunction Values which satisfy this predicate are subject to transformation
+         *            with {@code transformFunction}.
+         * @param transformFunction The transformation function.
+         */
         public void transform(Predicate<T> filterFunction, Function<T, T> transformFunction) {
-            for (Map.Entry<Integer, SizedValue<T>> entry : variables.entrySet()) {
-                SizedValue<T> value = entry.getValue();
+            for (Map.Entry<Integer, ValueWithSlots<T>> entry : variables.entrySet()) {
+                ValueWithSlots<T> value = entry.getValue();
                 if (filterFunction.test(value.value())) {
-                    entry.setValue(new SizedValue<>(transformFunction.apply(value.value()), value.size()));
+                    entry.setValue(new ValueWithSlots<>(transformFunction.apply(value.value()), value.size()));
                 }
             }
         }
@@ -222,27 +276,27 @@ public void transform(Predicate<T> filterFunction, Function<T, T> transformFunct
             this.variables = new HashMap<>(localVariableTable.variables);
         }
 
-        void put(int index, SizedValue<T> value) {
+        void put(int index, ValueWithSlots<T> value) {
             variables.put(index, value);
         }
 
-        SizedValue<T> get(int index) {
+        ValueWithSlots<T> get(int index) {
             GraalError.guarantee(variables.containsKey(index), "Attempted to access non-existent variable in local variable table");
             return variables.get(index);
         }
 
         void mergeWith(LocalVariableTable<T> other, BiFunction<T, T, T> mergeFunction) {
-            for (Map.Entry<Integer, SizedValue<T>> entry : variables.entrySet()) {
-                SizedValue<T> thisValue = entry.getValue();
-                SizedValue<T> thatValue = other.variables.get(entry.getKey());
+            for (Map.Entry<Integer, ValueWithSlots<T>> entry : variables.entrySet()) {
+                ValueWithSlots<T> thisValue = entry.getValue();
+                ValueWithSlots<T> thatValue = other.variables.get(entry.getKey());
                 if (thatValue != null && thisValue.size() == thatValue.size()) {
                     /*
                      * We can always merge matching values from the local variable table. If the
                      * merging makes no sense (i.e., the stored variable types do not match), we
                      * still allow it, as the resulting value should not be used during execution
                      * anyway (or else the method would fail bytecode verification).
                      */
-                    SizedValue<T> mergedValue = new SizedValue<>(mergeFunction.apply(thisValue.value(), thatValue.value()), thisValue.size());
+                    ValueWithSlots<T> mergedValue = new ValueWithSlots<>(mergeFunction.apply(thisValue.value(), thatValue.value()), thisValue.size());
                     entry.setValue(mergedValue);
                 }
             }
@@ -272,21 +326,25 @@ public String toString() {
             variables.entrySet().stream().sorted(Map.Entry.comparingByKey()).forEach(
                             e -> {
                                 Integer varIndex = e.getKey();
-                                SizedValue<T> value = e.getValue();
-                                builder.append(varIndex).append(": ").append(value.value()).append("\n");
+                                ValueWithSlots<T> value = e.getValue();
+                                builder.append(varIndex).append(": ").append(value.value()).append(System.lineSeparator());
                             });
             return builder.toString();
         }
     }
 
-    record SizedValue<T>(T value, Slots size) {
+    /**
+     * Wrapper which assigns a computational type category to a value, i.e., assigns the number of
+     * slots the value takes up in the local variable table or operand stack.
+     */
+    record ValueWithSlots<T>(T value, Slots size) {
         public enum Slots {
             ONE_SLOT,
             TWO_SLOTS
         }
 
-        public static <T> SizedValue<T> wrap(T value, Slots size) {
-            return new SizedValue<>(value, size);
+        public static <T> ValueWithSlots<T> wrap(T value, Slots size) {
+            return new ValueWithSlots<>(value, size);
         }
     }
 }