fix(javadoc): partial isthmus expression

isthmus/src/main/java/io/substrait/isthmus/expression/SqlMapValueConstructorCallConverter.java

@@ -13,10 +13,29 @@
 import org.apache.calcite.sql.SqlOperator;
 import org.apache.calcite.sql.fun.SqlMapValueConstructor;
 
+/**
+ * Converts Calcite {@link SqlMapValueConstructor} calls into Substrait map literals.
+ *
+ * <p>Expects an even-numbered operand list (key/value pairs) and produces an {@link Expression} map
+ * literal via {@link ExpressionCreator}.
+ */
 public class SqlMapValueConstructorCallConverter implements CallConverter {
 
   public SqlMapValueConstructorCallConverter() {}
 
+  /**
+   * Attempts to convert a Calcite {@link RexCall} representing a {@link SqlMapValueConstructor}
+   * into a Substrait map literal.
+   *
+   * @param call The Calcite call to convert.
+   * @param topLevelConverter Function for converting {@link RexNode} operands to Substrait {@link
+   *     Expression}s.
+   * @return An {@link Optional} containing the converted {@link Expression} if the operator is a
+   *     {@link SqlMapValueConstructor}; otherwise {@link Optional#empty()}.
+   * @throws ClassCastException if operands converted by {@code topLevelConverter} are not {@link
+   *     Expression.Literal} instances.
+   * @throws AssertionError if the number of operands is not even (expecting key/value pairs).
+   */
   @Override
   public Optional<Expression> convert(
       RexCall call, Function<RexNode, Expression> topLevelConverter) {

isthmus/src/main/java/io/substrait/isthmus/expression/WindowBoundConverter.java

@@ -7,9 +7,33 @@
 import org.apache.calcite.rex.RexWindowBound;
 import org.apache.calcite.sql.type.SqlTypeName;
 
+/**
+ * Utility for converting Calcite {@link RexWindowBound} to Substrait {@link WindowBound}.
+ *
+ * <p>Supports {@code CURRENT ROW}, {@code UNBOUNDED}, and integer-offset {@code PRECEDING}/{@code
+ * FOLLOWING} bounds.
+ */
 public class WindowBoundConverter {
 
-  /** Converts a {@link RexWindowBound} to a {@link WindowBound}. */
+  /**
+   * Converts a Calcite {@link RexWindowBound} to a Substrait {@link WindowBound}.
+   *
+   * <p>Accepted forms:
+   *
+   * <ul>
+   *   <li>{@code CURRENT ROW} → {@link WindowBound#CURRENT_ROW}
+   *   <li>{@code UNBOUNDED} → {@link WindowBound#UNBOUNDED}
+   *   <li>{@code PRECEDING n} / {@code FOLLOWING n} where {@code n} is an exact integer → {@link
+   *       WindowBound.Preceding}/{@link WindowBound.Following}
+   * </ul>
+   *
+   * @param rexWindowBound The Calcite window bound to convert.
+   * @return The corresponding Substrait {@link WindowBound}.
+   * @throws IllegalStateException if the bound is not one of CURRENT ROW, UNBOUNDED, PRECEDING, or
+   *     FOLLOWING.
+   * @throws IllegalArgumentException if the offset is not an exact integer type supported by
+   *     Substrait.
+   */
   public static WindowBound toWindowBound(RexWindowBound rexWindowBound) {
     if (rexWindowBound.isCurrentRow()) {
       return WindowBound.CURRENT_ROW;

isthmus/src/main/java/io/substrait/isthmus/expression/WindowFunctionConverter.java

@@ -24,22 +24,47 @@
 import org.apache.calcite.rex.RexWindow;
 import org.apache.calcite.sql.SqlAggFunction;
 
+/**
+ * Converts Calcite window function calls ({@link RexOver}) into Substrait {@link
+ * Expression.WindowFunctionInvocation}s using configured Substrait window function variants.
+ *
+ * <p>Handles partitioning, ordering, bounds (ROWS/RANGE, lower/upper), and DISTINCT/ALL invocation.
+ */
 public class WindowFunctionConverter
     extends FunctionConverter<
         SimpleExtension.WindowFunctionVariant,
         Expression.WindowFunctionInvocation,
         WindowFunctionConverter.WrappedWindowCall> {
 
+  /**
+   * Returns the supported window function signatures used for matching.
+   *
+   * @return immutable list of supported signatures.
+   */
   @Override
   protected ImmutableList<FunctionMappings.Sig> getSigs() {
     return FunctionMappings.WINDOW_SIGS;
   }
 
+  /**
+   * Creates a converter with the provided window function variants.
+   *
+   * @param functions Supported Substrait window function variants.
+   * @param typeFactory Calcite type factory for type handling.
+   */
   public WindowFunctionConverter(
       List<SimpleExtension.WindowFunctionVariant> functions, RelDataTypeFactory typeFactory) {
     super(functions, typeFactory);
   }
 
+  /**
+   * Creates a converter with provided function variants and additional signatures.
+   *
+   * @param functions Supported Substrait window function variants.
+   * @param additionalSignatures Extra signatures to consider during matching.
+   * @param typeFactory Calcite type factory for type handling.
+   * @param typeConverter Converter for Calcite/Substrait types.
+   */
   public WindowFunctionConverter(
       List<SimpleExtension.WindowFunctionVariant> functions,
       List<FunctionMappings.Sig> additionalSignatures,
@@ -48,6 +73,15 @@ public WindowFunctionConverter(
     super(functions, additionalSignatures, typeFactory, typeConverter);
   }
 
+  /**
+   * Generates a bound Substrait window function invocation for a matched call.
+   *
+   * @param call Wrapped window call, including {@link RexOver} and expression converter.
+   * @param function Selected Substrait function variant.
+   * @param arguments Converted Substrait function arguments.
+   * @param outputType Result type for the invocation.
+   * @return Built {@link Expression.WindowFunctionInvocation}.
+   */
   @Override
   protected Expression.WindowFunctionInvocation generateBinding(
       WrappedWindowCall call,
@@ -92,6 +126,19 @@ protected Expression.WindowFunctionInvocation generateBinding(
         arguments);
   }
 
+  /**
+   * Attempts to convert a Calcite {@link RexOver} call into a Substrait window function invocation.
+   *
+   * <p>Resolves the corresponding Substrait aggregate function variant, checks arity using
+   * signatures, and builds the invocation if match succeeds.
+   *
+   * @param over Calcite windowed aggregate call.
+   * @param topLevelConverter Function converting top-level {@link RexNode}s to Substrait {@link
+   *     Expression}s.
+   * @param rexExpressionConverter Converter for nested {@link RexNode} expressions.
+   * @return {@link Optional} containing the {@link Expression.WindowFunctionInvocation} if matched;
+   *     otherwise empty.
+   */
   public Optional<Expression.WindowFunctionInvocation> convert(
       RexOver over,
       Function<RexNode, Expression> topLevelConverter,

isthmus/src/main/java/io/substrait/isthmus/expression/WindowRelFunctionConverter.java

@@ -23,22 +23,48 @@
 import org.apache.calcite.rex.RexWindowBound;
 import org.apache.calcite.sql.SqlAggFunction;
 
+/**
+ * Converts Calcite window aggregate calls (from {@link Window.RexWinAggCall}) into Substrait {@link
+ * ConsistentPartitionWindow.WindowRelFunctionInvocation}s.
+ *
+ * <p>Handles bounds type (ROWS/RANGE), lower/upper bounds, DISTINCT/ALL invocation, and function
+ * signature matching against configured Substrait window function variants.
+ */
 public class WindowRelFunctionConverter
     extends FunctionConverter<
         SimpleExtension.WindowFunctionVariant,
         ConsistentPartitionWindow.WindowRelFunctionInvocation,
         WindowRelFunctionConverter.WrappedWindowRelCall> {
 
+  /**
+   * Returns the supported window function signatures used for matching.
+   *
+   * @return immutable list of supported signatures.
+   */
   @Override
   protected ImmutableList<FunctionMappings.Sig> getSigs() {
     return FunctionMappings.WINDOW_SIGS;
   }
 
+  /**
+   * Creates a converter with the provided window function variants.
+   *
+   * @param functions Supported Substrait window function variants.
+   * @param typeFactory Calcite type factory for type handling.
+   */
   public WindowRelFunctionConverter(
       List<SimpleExtension.WindowFunctionVariant> functions, RelDataTypeFactory typeFactory) {
     super(functions, typeFactory);
   }
 
+  /**
+   * Creates a converter with provided function variants and additional signatures.
+   *
+   * @param functions Supported Substrait window function variants.
+   * @param additionalSignatures Extra signatures to consider during matching.
+   * @param typeFactory Calcite type factory for type handling.
+   * @param typeConverter Converter for Calcite/Substrait types.
+   */
   public WindowRelFunctionConverter(
       List<SimpleExtension.WindowFunctionVariant> functions,
       List<FunctionMappings.Sig> additionalSignatures,
@@ -47,6 +73,15 @@ public WindowRelFunctionConverter(
     super(functions, additionalSignatures, typeFactory, typeConverter);
   }
 
+  /**
+   * Generates a bound Substrait window relation function invocation for a matched call.
+   *
+   * @param call Wrapped window rel call, including bounds and the original win-agg call.
+   * @param function Selected Substrait function variant.
+   * @param arguments Converted Substrait function arguments.
+   * @param outputType Result type for the invocation.
+   * @return Built {@link ConsistentPartitionWindow.WindowRelFunctionInvocation}.
+   */
   @Override
   protected ConsistentPartitionWindow.WindowRelFunctionInvocation generateBinding(
       WrappedWindowRelCall call,
@@ -77,6 +112,22 @@ protected ConsistentPartitionWindow.WindowRelFunctionInvocation generateBinding(
         arguments);
   }
 
+  /**
+   * Attempts to convert a Calcite {@link Window.RexWinAggCall} into a Substrait window relation
+   * function invocation.
+   *
+   * <p>Resolves the corresponding Substrait aggregate function variant, checks arity using
+   * signatures, and builds the invocation if match succeeds.
+   *
+   * @param winAggCall Calcite window aggregate call.
+   * @param lowerBound Lower bound of the window.
+   * @param upperBound Upper bound of the window.
+   * @param isRows Whether the window uses ROWS (true) or RANGE (false).
+   * @param topLevelConverter Function converting top-level {@link RexNode}s to Substrait {@link
+   *     Expression}s.
+   * @return {@link Optional} containing the {@link
+   *     ConsistentPartitionWindow.WindowRelFunctionInvocation} if matched; otherwise empty.
+   */
   public Optional<ConsistentPartitionWindow.WindowRelFunctionInvocation> convert(
       Window.RexWinAggCall winAggCall,
       RexWindowBound lowerBound,
@@ -127,18 +178,38 @@ public RelDataType getType() {
       return winAggCall.getType();
     }
 
+    /**
+     * Returns the underlying Calcite window aggregate call.
+     *
+     * @return the {@link Window.RexWinAggCall}.
+     */
     public Window.RexWinAggCall getWinAggCall() {
       return winAggCall;
     }
 
+    /**
+     * Returns the lower bound of the window.
+     *
+     * @return the {@link RexWindowBound} lower bound.
+     */
     public RexWindowBound getLowerBound() {
       return lowerBound;
     }
 
+    /**
+     * Returns the upper bound of the window.
+     *
+     * @return the {@link RexWindowBound} upper bound.
+     */
     public RexWindowBound getUpperBound() {
       return upperBound;
     }
 
+    /**
+     * Whether the window uses ROWS (true) or RANGE (false).
+     *
+     * @return {@code true} if ROWS; {@code false} if RANGE.
+     */
     public boolean isRows() {
       return isRows;
     }