docs, cleanup

src/main/java/org/perlonjava/runtime/RuntimeArrayProxy.java

@@ -1,25 +1,45 @@
 package org.perlonjava.runtime;
 
+/**
+ * RuntimeArrayProxy acts as a proxy for accessing elements within a RuntimeArray.
+ * It provides a mechanism to lazily initialize (vivify) elements in the array
+ * when they are accessed.
+ */
 public class RuntimeArrayProxy extends RuntimeBaseProxy {
+    // Reference to the parent RuntimeArray
     private final RuntimeArray parent;
+    // Index associated with this proxy in the parent array
     private final int key;
 
+    /**
+     * Constructs a RuntimeArrayProxy for a given index in the specified parent array.
+     *
+     * @param parent the parent RuntimeArray containing the elements
+     * @param key    the index in the array for which this proxy is created
+     */
     public RuntimeArrayProxy(RuntimeArray parent, int key) {
         super();
         this.parent = parent;
         this.key = key;
         // Note: this.type is RuntimeScalarType.UNDEF
     }
 
+    /**
+     * Vivifies (initializes) the element in the parent array if it does not exist.
+     * If the element at the specified index is not present, it creates new
+     * RuntimeScalar instances up to that index and assigns them in the parent array.
+     */
     void vivify() {
         if (lvalue == null) {
+            // Check if the index is beyond the current size of the array
             if (key >= parent.elements.size()) {
+                // Add new RuntimeScalar instances up to the specified index
                 for (int i = parent.elements.size(); i <= key; i++) {
                     parent.elements.add(i, new RuntimeScalar());
                 }
             }
+            // Retrieve the element at the specified index
             lvalue = parent.elements.get(key);
         }
     }
 }
-

src/main/java/org/perlonjava/runtime/RuntimeBaseEntity.java

@@ -1,27 +1,58 @@
 package org.perlonjava.runtime;
 
 /**
- * The RuntimeBaseEntity class is a base class for scalar, hash, and array variables.
+ * The RuntimeBaseEntity class serves as an abstract base class for scalar, hash,
+ * and array variables in the runtime environment. It provides common functionality
+ * and interfaces for these entities.
  */
 public abstract class RuntimeBaseEntity implements RuntimeDataProvider {
     // Index to the class that this reference belongs
     public int blessId;
 
-    // Add the object to a list
+    /**
+     * Adds this entity to the specified RuntimeList.
+     *
+     * @param list the RuntimeList to which this entity will be added
+     */
     public void addToList(RuntimeList list) {
         list.add(this);
     }
 
-    // Get the array value of the object as aliases
+    /**
+     * Retrieves the array value of the object as aliases.
+     * This method initializes a new RuntimeArray and sets it as the alias for this entity.
+     *
+     * @return a RuntimeArray representing the array of aliases for this entity
+     */
     public RuntimeArray getArrayOfAlias() {
         RuntimeArray arr = new RuntimeArray();
         this.setArrayOfAlias(arr);
         return arr;
     }
 
-    // Get the total number of elements in all elements of the list as a RuntimeScalar
+    /**
+     * Gets the total number of elements in all elements of the list as a RuntimeScalar.
+     * This method provides a count of elements, useful for determining the size of collections.
+     *
+     * @return a RuntimeScalar representing the count of elements
+     */
     public RuntimeScalar count() {
         return new RuntimeScalar(countElements());
     }
-}
 
+    /**
+     * Abstract method to set the array of aliases for this entity.
+     * Subclasses should provide an implementation for this method.
+     *
+     * @param arr the RuntimeArray to be set as the array of aliases
+     */
+    public abstract RuntimeArray setArrayOfAlias(RuntimeArray arr);
+
+    /**
+     * Abstract method to count the elements within this entity.
+     * Subclasses should provide an implementation for this method.
+     *
+     * @return the number of elements as an integer
+     */
+    public abstract int countElements();
+}

src/main/java/org/perlonjava/runtime/RuntimeHashProxy.java

@@ -1,23 +1,43 @@
 package org.perlonjava.runtime;
 
+/**
+ * RuntimeHashProxy acts as a proxy for accessing elements within a RuntimeHash.
+ * It provides a mechanism to lazily initialize (vivify) elements in the hash
+ * when they are accessed.
+ */
 public class RuntimeHashProxy extends RuntimeBaseProxy {
+    // Reference to the parent RuntimeHash
     private final RuntimeHash parent;
+    // Key associated with this proxy in the parent hash
     private final String key;
 
+    /**
+     * Constructs a RuntimeHashProxy for a given key in the specified parent hash.
+     *
+     * @param parent the parent RuntimeHash containing the elements
+     * @param key    the key in the hash for which this proxy is created
+     */
     public RuntimeHashProxy(RuntimeHash parent, String key) {
         super();
         this.parent = parent;
         this.key = key;
         // Note: this.type is RuntimeScalarType.UNDEF
     }
 
+    /**
+     * Vivifies (initializes) the element in the parent hash if it does not exist.
+     * If the element associated with the key is not present, it creates a new
+     * RuntimeScalar and assigns it to the key in the parent hash.
+     */
     void vivify() {
         if (lvalue == null) {
+            // Check if the key is not present in the hash
             if (!parent.elements.containsKey(key)) {
+                // Add a new RuntimeScalar for the key
                 parent.elements.put(key, new RuntimeScalar());
             }
+            // Retrieve the element associated with the key
             lvalue = parent.elements.get(key);
         }
     }
 }
-