fix: add javadoc to core (part i)

core/src/main/java/io/substrait/expression/AbstractFunctionInvocation.java

@@ -4,21 +4,63 @@
 import io.substrait.type.Type;
 import java.util.List;
 
+/**
+ * Represents a generic function invocation, including its declaration, arguments, aggregation
+ * phase, sort fields, output type, and invocation details.
+ *
+ * @param <T> the function type (from {@link SimpleExtension})
+ * @param <I> the invocation-specific type
+ */
 public abstract class AbstractFunctionInvocation<T extends SimpleExtension.Function, I> {
 
+  /**
+   * Returns the function declaration associated with this invocation.
+   *
+   * @return the function declaration
+   */
   public abstract T declaration();
 
+  /**
+   * Returns the ordered list of function arguments.
+   *
+   * @return list of function arguments
+   */
   public abstract List<FunctionArg> arguments();
 
+  /**
+   * Returns the aggregation phase for this invocation, if applicable.
+   *
+   * @return aggregation phase or {@code null} if not an aggregate
+   */
   public abstract Expression.AggregationPhase aggregationPhase();
 
+  /**
+   * Returns the sort fields applied to this invocation, if any.
+   *
+   * @return list of sort fields
+   */
   public abstract List<Expression.SortField> sort();
 
+  /**
+   * Returns the output type produced by this invocation.
+   *
+   * @return the output type
+   */
   public abstract Type outputType();
 
+  /**
+   * Returns the type of this invocation (same as {@link #outputType()}).
+   *
+   * @return the output type
+   */
   public Type getType() {
     return outputType();
   }
 
+  /**
+   * Returns the invocation-specific details.
+   *
+   * @return invocation details
+   */
   public abstract I invocation();
 }

core/src/main/java/io/substrait/expression/AggregateFunctionInvocation.java

@@ -5,36 +5,88 @@
 import java.util.List;
 import org.immutables.value.Value;
 
+/**
+ * Represents an aggregate function invocation, including its declaration, arguments, options,
+ * aggregation phase, sort fields, output type, and invocation semantics.
+ */
 @Value.Immutable
 public abstract class AggregateFunctionInvocation {
+
+  /**
+   * Returns the aggregate function variant declaration.
+   *
+   * @return the function variant declaration
+   */
   public abstract SimpleExtension.AggregateFunctionVariant declaration();
 
+  /**
+   * Returns the ordered list of function arguments.
+   *
+   * @return list of function arguments
+   */
   public abstract List<FunctionArg> arguments();
 
+  /**
+   * Returns the options applied to this aggregate function.
+   *
+   * @return list of function options
+   */
   public abstract List<FunctionOption> options();
 
+  /**
+   * Returns the aggregation phase (e.g., initial, intermediate, final).
+   *
+   * @return aggregation phase
+   */
   public abstract Expression.AggregationPhase aggregationPhase();
 
+  /**
+   * Returns the sort fields applied to this invocation, if any.
+   *
+   * @return list of sort fields
+   */
   public abstract List<Expression.SortField> sort();
 
+  /**
+   * Returns the output type produced by this invocation.
+   *
+   * @return the output type
+   */
   public abstract Type outputType();
 
+  /**
+   * Returns the type of this invocation (same as {@link #outputType()}).
+   *
+   * @return the output type
+   */
   public Type getType() {
     return outputType();
   }
 
+  /**
+   * Returns the aggregation invocation semantics (e.g., aggregate, merge).
+   *
+   * @return aggregation invocation
+   */
   public abstract Expression.AggregationInvocation invocation();
 
   /**
    * Validates that variadic arguments satisfy the parameter consistency requirement. When
    * CONSISTENT, all variadic arguments must have the same type (ignoring nullability). When
    * INCONSISTENT, arguments can have different types.
+   *
+   * @throws IllegalArgumentException if validation fails
    */
   @Value.Check
   protected void check() {
     VariadicParameterConsistencyValidator.validate(declaration(), arguments());
   }
 
+  /**
+   * Creates a builder for {@link AggregateFunctionInvocation}.
+   *
+   * @return a new immutable builder
+   */
   public static ImmutableAggregateFunctionInvocation.Builder builder() {
     return ImmutableAggregateFunctionInvocation.builder();
   }

core/src/main/java/io/substrait/extendedexpression/ExtendedExpression.java

@@ -8,37 +8,89 @@
 import java.util.Optional;
 import org.immutables.value.Value;
 
+/**
+ * Represents an extended expression that references multiple expressions and schema details.
+ *
+ * <p>Includes references to expressions, expected type URLs, and optional advanced extensions.
+ */
 @Value.Immutable
 public abstract class ExtendedExpression {
+
+  /**
+   * Returns the list of referred expression references.
+   *
+   * @return list of expression references
+   */
   public abstract List<ExpressionReferenceBase> getReferredExpressions();
 
+  /**
+   * Returns the base schema associated with this extended expression.
+   *
+   * @return the base schema
+   */
   public abstract NamedStruct getBaseSchema();
 
+  /**
+   * Returns the expected type URLs for validation.
+   *
+   * @return list of expected type URLs
+   */
   public abstract List<String> getExpectedTypeUrls();
 
-  // creating simple extensions, such as extensionURIs and extensions, is performed on the fly
-
+  /**
+   * Returns the optional advanced extension metadata.
+   *
+   * @return optional advanced extension
+   */
   public abstract Optional<AdvancedExtension> getAdvancedExtension();
 
+  /**
+   * Creates a builder for {@link ExtendedExpression}.
+   *
+   * @return a new builder
+   */
   public static ImmutableExtendedExpression.Builder builder() {
     return ImmutableExtendedExpression.builder();
   }
 
+  /** Base interface for expression references. */
   public interface ExpressionReferenceBase {
+    /**
+     * Returns the output names associated with this reference.
+     *
+     * @return list of output names
+     */
     List<String> getOutputNames();
   }
 
+  /** Represents a reference to a single expression. */
   @Value.Immutable
   public abstract static class ExpressionReference implements ExpressionReferenceBase {
+    /**
+     * Returns the referenced expression.
+     *
+     * @return the expression
+     */
     public abstract Expression getExpression();
 
+    /**
+     * Creates a builder for {@link ExpressionReference}.
+     *
+     * @return a new builder
+     */
     public static ImmutableExpressionReference.Builder builder() {
       return ImmutableExpressionReference.builder();
     }
   }
 
+  /** Represents a reference to an aggregate function measure. */
   @Value.Immutable
   public abstract static class AggregateFunctionReference implements ExpressionReferenceBase {
+    /**
+     * Returns the referenced aggregate measure.
+     *
+     * @return the measure
+     */
     public abstract Aggregate.Measure getMeasure();
   }
 }

core/src/main/java/io/substrait/extension/DefaultExtensionCatalog.java

@@ -4,28 +4,64 @@
 import java.util.List;
 import java.util.stream.Collectors;
 
+/**
+ * Provides default extension catalog constants and utilities for loading built-in Substrait
+ * function definitions.
+ */
 public class DefaultExtensionCatalog {
+
+  /** Extension identifier for approximate aggregate functions. */
   public static final String FUNCTIONS_AGGREGATE_APPROX =
       "extension:io.substrait:functions_aggregate_approx";
+
+  /** Extension identifier for generic aggregate functions. */
   public static final String FUNCTIONS_AGGREGATE_GENERIC =
       "extension:io.substrait:functions_aggregate_generic";
+
+  /** Extension identifier for arithmetic functions. */
   public static final String FUNCTIONS_ARITHMETIC = "extension:io.substrait:functions_arithmetic";
+
+  /** Extension identifier for decimal arithmetic functions. */
   public static final String FUNCTIONS_ARITHMETIC_DECIMAL =
       "extension:io.substrait:functions_arithmetic_decimal";
+
+  /** Extension identifier for boolean functions. */
   public static final String FUNCTIONS_BOOLEAN = "extension:io.substrait:functions_boolean";
+
+  /** Extension identifier for comparison functions. */
   public static final String FUNCTIONS_COMPARISON = "extension:io.substrait:functions_comparison";
+
+  /** Extension identifier for datetime functions. */
   public static final String FUNCTIONS_DATETIME = "extension:io.substrait:functions_datetime";
+
+  /** Extension identifier for geometry functions. */
   public static final String FUNCTIONS_GEOMETRY = "extension:io.substrait:functions_geometry";
+
+  /** Extension identifier for logarithmic functions. */
   public static final String FUNCTIONS_LOGARITHMIC = "extension:io.substrait:functions_logarithmic";
+
+  /** Extension identifier for rounding functions. */
   public static final String FUNCTIONS_ROUNDING = "extension:io.substrait:functions_rounding";
+
+  /** Extension identifier for decimal rounding functions. */
   public static final String FUNCTIONS_ROUNDING_DECIMAL =
       "extension:io.substrait:functions_rounding_decimal";
+
+  /** Extension identifier for set functions. */
   public static final String FUNCTIONS_SET = "extension:io.substrait:functions_set";
+
+  /** Extension identifier for string functions. */
   public static final String FUNCTIONS_STRING = "extension:io.substrait:functions_string";
 
+  /** Default collection of built-in extensions loaded from YAML resources. */
   public static final SimpleExtension.ExtensionCollection DEFAULT_COLLECTION =
       loadDefaultCollection();
 
+  /**
+   * Loads the default extension collection from predefined YAML files.
+   *
+   * @return the loaded extension collection
+   */
   private static SimpleExtension.ExtensionCollection loadDefaultCollection() {
     List<String> defaultFiles =
         Arrays.asList(