Add missing javadoc

Author: daniellansun

src/main/java/org/codehaus/groovy/reflection/stdclasses/ArrayCachedClass.java

@@ -25,11 +25,30 @@
 
 import java.lang.reflect.Array;
 
+/**
+ * Provides optimized reflection caching for Java arrays.
+ * Handles type coercion including conversion of boxed arrays to primitive arrays,
+ * and {@link GString} arrays to {@link String} arrays.
+ */
 public class ArrayCachedClass extends CachedClass {
+    /**
+     * Constructs a cached class representation for the given array class.
+     *
+     * @param klazz the array class to cache
+     * @param classInfo the class information associated with this cached class
+     */
     public ArrayCachedClass(Class klazz, ClassInfo classInfo) {
         super(klazz, classInfo);
     }
 
+    /**
+     * Coerces the given argument to the appropriate array type.
+     * Converts boxed arrays to primitive arrays if needed, and
+     * {@link GString} arrays to {@link String} arrays.
+     *
+     * @param argument the argument to coerce
+     * @return the coerced argument, or the original argument if no coercion is needed
+     */
     @Override
     public Object coerceArgument(Object argument) {
         Class argumentClass = argument.getClass();

src/main/java/org/codehaus/groovy/reflection/stdclasses/BigDecimalCachedClass.java

@@ -23,16 +23,38 @@
 
 import java.math.BigDecimal;
 
+/**
+ * Provides optimized reflection caching for {@link java.math.BigDecimal}.
+ * Coerces numeric arguments to {@link BigDecimal} for type-safe method invocation.
+ */
 public class BigDecimalCachedClass extends DoubleCachedClass {
+    /**
+     * Constructs a cached class representation for {@link BigDecimal}.
+     *
+     * @param klazz the {@link BigDecimal} class to cache
+     * @param classInfo the class information associated with this cached class
+     */
     public BigDecimalCachedClass(Class klazz, ClassInfo classInfo) {
         super(klazz, classInfo, true);
     }
 
+    /**
+     * Checks if the given argument is directly assignable to {@link BigDecimal}.
+     *
+     * @param argument the argument to check
+     * @return {@code true} if the argument is an instance of {@link BigDecimal}, {@code false} otherwise
+     */
     @Override
     public boolean isDirectlyAssignable(Object argument) {
         return argument instanceof BigDecimal;
     }
 
+    /**
+     * Coerces the given numeric argument to {@link BigDecimal}.
+     *
+     * @param argument the argument to coerce
+     * @return the argument as a {@link BigDecimal}, or the original argument if not a number
+     */
     @Override
     public Object coerceArgument(Object argument) {
         if (argument instanceof Number) {

src/main/java/org/codehaus/groovy/reflection/stdclasses/BigIntegerCachedClass.java

@@ -22,16 +22,39 @@
 
 import java.math.BigInteger;
 
+/**
+ * Provides optimized reflection caching for {@link java.math.BigInteger}.
+ * Coerces integral and big numeric types to {@link BigInteger} for type-safe method invocation.
+ */
 public class BigIntegerCachedClass extends NumberCachedClass {
+    /**
+     * Constructs a cached class representation for {@link BigInteger}.
+     *
+     * @param klazz the {@link BigInteger} class to cache
+     * @param classInfo the class information associated with this cached class
+     */
     public BigIntegerCachedClass(Class klazz, ClassInfo classInfo) {
         super(klazz, classInfo);
     }
 
+    /**
+     * Checks if the given argument is directly assignable to {@link BigInteger}.
+     *
+     * @param argument the argument to check
+     * @return {@code true} if the argument is an instance of {@link BigInteger}, {@code false} otherwise
+     */
     @Override
     public boolean isDirectlyAssignable(Object argument) {
         return argument instanceof BigInteger;
     }
 
+    /**
+     * Determines if the given class can be transformed to {@link BigInteger}.
+     * Accepts integral types, boxed integral types, and other big numeric types.
+     *
+     * @param classToTransformFrom the source class to check
+     * @return {@code true} if the class can be transformed to {@link BigInteger}, {@code false} otherwise
+     */
     @Override
     public boolean isAssignableFrom(Class classToTransformFrom) {
         return classToTransformFrom == null

src/main/java/org/codehaus/groovy/reflection/stdclasses/BooleanCachedClass.java

@@ -21,18 +21,42 @@
 import org.codehaus.groovy.reflection.CachedClass;
 import org.codehaus.groovy.reflection.ClassInfo;
 
+/**
+ * Provides optimized reflection caching for {@code boolean} and {@link java.lang.Boolean}.
+ * Optionally allows {@code null} values for the boxed {@link Boolean} class variant.
+ */
 public class BooleanCachedClass extends CachedClass {
     private final boolean allowNull;
+
+    /**
+     * Constructs a cached class representation for the given boolean class.
+     *
+     * @param klazz the boolean class to cache (either {@code boolean.class} or {@link Boolean}.class)
+     * @param classInfo the class information associated with this cached class
+     * @param allowNull {@code true} to allow {@code null} values (for {@link Boolean}.class), {@code false} for primitive {@code boolean}
+     */
     public BooleanCachedClass(Class klazz, ClassInfo classInfo, boolean allowNull) {
         super(klazz, classInfo);
         this.allowNull = allowNull;
     }
 
+    /**
+     * Checks if the given argument is directly assignable without type conversion.
+     *
+     * @param argument the argument to check
+     * @return {@code true} if the argument is a {@link Boolean} instance, or {@code null} is allowed, {@code false} otherwise
+     */
     @Override
     public boolean isDirectlyAssignable(Object argument) {
         return (allowNull && argument == null) || argument instanceof Boolean;
      }
 
+    /**
+     * Determines if the given class can be transformed to boolean/Boolean.
+     *
+     * @param classToTransformFrom the source class to check
+     * @return {@code true} if the class can be transformed to boolean, {@code false} otherwise
+     */
     @Override
     public boolean isAssignableFrom(Class classToTransformFrom) {
         return (allowNull && classToTransformFrom == null)

src/main/java/org/codehaus/groovy/reflection/stdclasses/ByteCachedClass.java

@@ -20,13 +20,32 @@
 
 import org.codehaus.groovy.reflection.ClassInfo;
 
+/**
+ * Provides optimized reflection caching for {@code byte} and {@link java.lang.Byte}.
+ * Coerces numeric arguments to byte values for type-safe method invocation.
+ * Optionally allows {@code null} values for the boxed {@link Byte} class variant.
+ */
 public class ByteCachedClass extends NumberCachedClass {
     private final boolean allowNull;
+
+    /**
+     * Constructs a cached class representation for the given byte class.
+     *
+     * @param klazz the byte class to cache (either {@code byte.class} or {@link Byte}.class)
+     * @param classInfo the class information associated with this cached class
+     * @param allowNull {@code true} to allow {@code null} values (for {@link Byte}.class), {@code false} for primitive {@code byte}
+     */
     public ByteCachedClass(Class klazz, ClassInfo classInfo, boolean allowNull) {
         super(klazz, classInfo);
         this.allowNull = allowNull;
     }
 
+    /**
+     * Coerces the given numeric argument to a byte value.
+     *
+     * @param argument the argument to coerce
+     * @return the argument as a {@code byte}, or the original argument if not a number
+     */
     @Override
     public Object coerceArgument(Object argument) {
         if (argument instanceof Byte) {
@@ -39,11 +58,23 @@ public Object coerceArgument(Object argument) {
         return argument;
     }
 
+    /**
+     * Checks if the given argument is directly assignable without type conversion.
+     *
+     * @param argument the argument to check
+     * @return {@code true} if the argument is a {@link Byte} instance, or {@code null} is allowed, {@code false} otherwise
+     */
     @Override
     public boolean isDirectlyAssignable(Object argument) {
         return (allowNull && argument == null) || argument instanceof Byte;
     }
 
+    /**
+     * Determines if the given class can be transformed to byte/Byte.
+     *
+     * @param classToTransformFrom the source class to check
+     * @return {@code true} if the class can be transformed to byte, {@code false} otherwise
+     */
     @Override
     public boolean isAssignableFrom(Class classToTransformFrom) {
         return (allowNull && classToTransformFrom == null)

src/main/java/org/codehaus/groovy/reflection/stdclasses/CachedClosureClass.java

@@ -22,10 +22,21 @@
 import org.codehaus.groovy.reflection.CachedMethod;
 import org.codehaus.groovy.reflection.ClassInfo;
 
+/**
+ * Provides optimized reflection caching for Groovy {@link groovy.lang.Closure} classes.
+ * Analyzes closure {@code doCall} methods to determine parameter types and maximum parameters.
+ */
 public class CachedClosureClass extends CachedClass {
     private final Class[] parameterTypes;
     private final int maximumNumberOfParameters;
 
+    /**
+     * Constructs a cached class representation for a closure class.
+     * Inspects the closure's {@code doCall} methods to extract parameter metadata.
+     *
+     * @param klazz the closure class to cache
+     * @param classInfo the class information associated with this cached class
+     */
     public CachedClosureClass(Class klazz, ClassInfo classInfo) {
         super(klazz, classInfo);
 
@@ -51,10 +62,20 @@ public CachedClosureClass(Class klazz, ClassInfo classInfo) {
         this.parameterTypes = parameterTypes;
     }
 
+    /**
+     * Returns the parameter types of the closure's {@code doCall} method with maximum parameters.
+     *
+     * @return the parameter types array, or {@code null} if no {@code doCall} method was found
+     */
     public Class[] getParameterTypes() {
         return parameterTypes;
     }
 
+    /**
+     * Returns the maximum number of parameters accepted by the closure's {@code doCall} methods.
+     *
+     * @return the maximum number of parameters, or {@code 0} if no {@code doCall} method was found
+     */
     public int getMaximumNumberOfParameters() {
         return maximumNumberOfParameters;
     }

src/main/java/org/codehaus/groovy/reflection/stdclasses/CachedSAMClass.java

@@ -39,23 +39,49 @@
 import java.util.Set;
 import java.util.stream.Collectors;
 
+/**
+ * Provides optimized reflection caching for Single Abstract Method (SAM) types.
+ * Converts {@link Closure} arguments to SAM interface implementations via dynamic proxies or aggregates.
+ */
 public class CachedSAMClass extends CachedClass {
 
     private final Method method;
 
+    /**
+     * Constructs a cached class representation for a SAM type.
+     * Locates and caches the single abstract method of the class.
+     *
+     * @param clazz the SAM type to cache
+     * @param classInfo the class information associated with this cached class
+     * @throws GroovyBugError if the class does not have exactly one abstract method
+     */
     public CachedSAMClass(Class clazz, ClassInfo classInfo) {
         super(clazz, classInfo);
         method = getSAMMethod(clazz);
         if (method == null) throw new GroovyBugError("assigned method should not have been null!");
     }
 
+    /**
+     * Determines if the given class is assignable to this SAM type.
+     * Accepts {@code null}, {@link Closure} instances, and instances already assignable to the SAM type.
+     *
+     * @param argument the class to check
+     * @return {@code true} if the class can be assigned to this SAM type, {@code false} otherwise
+     */
     @Override
     public boolean isAssignableFrom(Class argument) {
         return argument == null
             || Closure.class.isAssignableFrom(argument)
             || getTheClass().isAssignableFrom(argument);
     }
 
+    /**
+     * Coerces the given argument to this SAM type.
+     * Converts {@link Closure} arguments to SAM interface implementations via dynamic proxies.
+     *
+     * @param argument the argument to coerce
+     * @return the coerced SAM instance, or the original argument if already compatible
+     */
     @Override
     public Object coerceArgument(Object argument) {
         if (argument instanceof Closure) {
@@ -73,10 +99,30 @@ public Object coerceArgument(Object argument) {
     private static final int ABSTRACT_STATIC_PRIVATE = Modifier.ABSTRACT | Modifier.STATIC | Modifier.PRIVATE;
     private static final Set<String> OBJECT_METHOD_NAMES = Arrays.stream(Object.class.getMethods()).map(Method::getName).collect(Collectors.toUnmodifiableSet());
 
+    /**
+     * Coerces a closure to a SAM interface implementation.
+     * Automatically detects whether the SAM type is an interface or class.
+     *
+     * @param argument the closure to convert
+     * @param method the single abstract method of the SAM type
+     * @param clazz the SAM class or interface to coerce to
+     * @return a dynamic proxy or aggregate instance implementing the SAM type
+     */
     public static Object coerceToSAM(Closure argument, Method method, Class clazz) {
         return coerceToSAM(argument, method, clazz, clazz.isInterface());
     }
 
+    /**
+     * Coerces a closure to a SAM interface or class implementation.
+     * For interfaces, uses dynamic proxies or trait-aware aggregates.
+     * For classes, uses proxy generators to instantiate from base class.
+     *
+     * @param argument the closure to convert
+     * @param method the single abstract method of the SAM type
+     * @param clazz the SAM class or interface to coerce to
+     * @param isInterface {@code true} if the SAM type is an interface, {@code false} for a class
+     * @return a dynamic proxy or aggregate instance implementing the SAM type
+     */
     public static Object coerceToSAM(Closure argument, Method method, Class clazz, boolean isInterface) {
         if (argument != null && clazz.isAssignableFrom(argument.getClass())) {
             return argument;

src/main/java/org/codehaus/groovy/reflection/stdclasses/CharacterCachedClass.java

@@ -21,19 +21,42 @@
 import org.codehaus.groovy.reflection.CachedClass;
 import org.codehaus.groovy.reflection.ClassInfo;
 
+/**
+ * Provides optimized reflection caching for {@code char} and {@link java.lang.Character}.
+ * Optionally allows {@code null} values for the boxed {@link Character} class variant.
+ */
 public class CharacterCachedClass extends CachedClass {
     private final boolean allowNull;
 
+    /**
+     * Constructs a cached class representation for the given character class.
+     *
+     * @param klazz the character class to cache (either {@code char.class} or {@link Character}.class)
+     * @param classInfo the class information associated with this cached class
+     * @param allowNull {@code true} to allow {@code null} values (for {@link Character}.class), {@code false} for primitive {@code char}
+     */
     public CharacterCachedClass(Class klazz, ClassInfo classInfo, boolean allowNull) {
         super(klazz, classInfo);
         this.allowNull = allowNull;
     }
 
+    /**
+     * Checks if the given argument is directly assignable without type conversion.
+     *
+     * @param argument the argument to check
+     * @return {@code true} if the argument is a {@link Character} instance, or {@code null} is allowed, {@code false} otherwise
+     */
     @Override
     public boolean isDirectlyAssignable(Object argument) {
         return (allowNull && argument == null) || argument instanceof Character;
     }
 
+    /**
+     * Determines if the given class can be transformed to char/Character.
+     *
+     * @param classToTransformFrom the source class to check
+     * @return {@code true} if the class can be transformed to char, {@code false} otherwise
+     */
     @Override
     public boolean isAssignableFrom(Class classToTransformFrom) {
         return (allowNull && classToTransformFrom == null)