docs, cleanup

src/main/java/org/perlonjava/runtime/MatcherViewArray.java → src/main/java/org/perlonjava/runtime/ArraySpecialVariable.java

@@ -5,29 +5,30 @@
 import static org.perlonjava.runtime.RuntimeScalarCache.scalarUndef;
 
 /**
- * MatcherViewArray provides a dynamic view over a Matcher object,
- * representing the end positions of each capturing group in the Matcher.
+ * ArraySpecialVariable provides a dynamic view over an internal object, such as a Matcher object,
+ * representing the start or end positions of each capturing group in the Matcher.
  * This class does not store data internally but queries the Matcher
  * whenever its methods are called, ensuring it reflects the current state
  * of the Matcher.
  */
-public class MatcherViewArray extends AbstractList<RuntimeScalar> {
+public class ArraySpecialVariable extends AbstractList<RuntimeScalar> {
 
+    // Mode of operation for this special variable, determining whether it tracks start or end positions
     private final Id mode;
 
     /**
-     * Constructs a MatcherViewArray for the given Matcher with a specified mode.
+     * Constructs an ArraySpecialVariable for the given mode.
      *
-     * @param mode the mode of operation
+     * @param mode the mode of operation, determining whether to track start or end positions
      */
-    public MatcherViewArray(Id mode) {
+    public ArraySpecialVariable(Id mode) {
         this.mode = mode;
     }
 
     /**
      * Returns the position of the capturing group at the specified index.
-     * The position returned depends on the mode: end position for Id.END,
-     * and start position for Id.START.
+     * The position returned depends on the mode: end position for Id.LAST_MATCH_END,
+     * and start position for Id.LAST_MATCH_START.
      *
      * @param index the index of the capturing group
      * @return a RuntimeScalar representing the position of the group
@@ -62,11 +63,11 @@ public int size() {
     }
 
     /**
-     * Enum to represent the mode of operation for MatcherViewArray.
-     * END corresponds to "@+" (end positions), and START corresponds to "@-" (start positions).
+     * Enum to represent the mode of operation for ArraySpecialVariable.
+     * LAST_MATCH_END corresponds to "@+" (end positions), and LAST_MATCH_START corresponds to "@-" (start positions).
      */
     public enum Id {
         LAST_MATCH_END,  // Represents the end positions of capturing groups
         LAST_MATCH_START // Represents the start positions of capturing groups
     }
-}
+}

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

@@ -60,8 +60,8 @@ public static void initializeGlobals(ArgumentParser.CompilerOptions compilerOpti
         globalVariables.put("main::'", new ScalarSpecialVariable(ScalarSpecialVariable.Id.POSTMATCH));
 
         // Initialize arrays
-        getGlobalArray("main::+").elements = new MatcherViewArray(MatcherViewArray.Id.LAST_MATCH_END);  // regex @+
-        getGlobalArray("main::-").elements = new MatcherViewArray(MatcherViewArray.Id.LAST_MATCH_START);  // regex @-
+        getGlobalArray("main::+").elements = new ArraySpecialVariable(ArraySpecialVariable.Id.LAST_MATCH_END);  // regex @+
+        getGlobalArray("main::-").elements = new ArraySpecialVariable(ArraySpecialVariable.Id.LAST_MATCH_START);  // regex @-
 
         // Initialize %ENV
         Map<String, RuntimeScalar> env = getGlobalHash("main::ENV").elements;

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

@@ -2,20 +2,42 @@
 
 import java.util.*;
 
+/**
+ * The InheritanceResolver class provides methods for resolving method inheritance
+ * and linearizing class hierarchies using the C3 algorithm. It maintains caches
+ * for method resolution and linearized class hierarchies to improve performance.
+ */
 public class InheritanceResolver {
     // Method resolution cache
     private static final Map<String, RuntimeScalar> methodCache = new HashMap<>();
+    // Cache for linearized class hierarchies
     private static final Map<String, List<String>> linearizedClassesCache = new HashMap<>();
 
+    /**
+     * Invalidates the caches for method resolution and linearized class hierarchies.
+     * This should be called whenever the class hierarchy or method definitions change.
+     */
     public static void invalidateCache() {
         methodCache.clear();
         linearizedClassesCache.clear();
     }
 
+    /**
+     * Retrieves a cached method for the given normalized method name.
+     *
+     * @param normalizedMethodName The normalized name of the method.
+     * @return The cached RuntimeScalar representing the method, or null if not found.
+     */
     public static RuntimeScalar getCachedMethod(String normalizedMethodName) {
         return methodCache.get(normalizedMethodName);
     }
 
+    /**
+     * Caches a method for the given normalized method name.
+     *
+     * @param normalizedMethodName The normalized name of the method.
+     * @param method               The RuntimeScalar representing the method to cache.
+     */
     public static void cacheMethod(String normalizedMethodName, RuntimeScalar method) {
         methodCache.put(normalizedMethodName, method);
     }