Improve RowFn batch documentation

Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>

Author: connortsui20

vortex-array/src/scalar_fn/unstable/row/batch/args.rs

@@ -4,15 +4,15 @@
 //! Execution arguments paired with the metadata selected during planning.
 //!
 //! [`BorrowedExecutionArgs`] can point at original or sliced arrays while retaining the dtypes,
-//! output dtype, and null policy of the original batch plan.
+//! output dtype, and execution policy of the original batch plan.
 
 use vortex_error::VortexResult;
 use vortex_error::vortex_err;
 
+use super::RowPolicy;
 use crate::ArrayRef;
 use crate::dtype::DType;
 use crate::scalar_fn::ExecutionArgs;
-use crate::scalar_fn::unstable::row::visitor::RowPolicy;
 
 /// A borrowed [`ExecutionArgs`] view with the metadata selected for its row function.
 ///

vortex-array/src/scalar_fn/unstable/row/batch/execute/mod.rs

@@ -29,8 +29,8 @@ pub(crate) use output::finalize_kernel_output;
 impl Batch {
     /// Apply constant folding and null handling around `kernel`.
     ///
-    /// When the mask contains valid and invalid rows, `try_valid_rows` executes only valid rows
-    /// over the original inputs. Every result is checked against the planned shape and dtype.
+    /// For a partially valid batch, `try_valid_rows` executes only valid rows over the original
+    /// inputs. Every result is checked against the planned shape and dtype.
     pub(crate) fn execute(
         &self,
         kernel: impl Fn(BorrowedExecutionArgs<'_>, &mut ExecutionCtx) -> VortexResult<ArrayRef>,
@@ -53,8 +53,9 @@ impl Batch {
             return Ok(self.all_null());
         }
 
-        // All inputs constant, and their conjoined validity proves every row non-null. This sees
-        // through extension and masked wrappers just like argument decoding does.
+        // All inputs are constant, and their conjoined validity proves that every row is non-null.
+        // The constant check sees through extension and masked wrappers, just like argument
+        // decoding.
         if self.row_count > 0
             && self.validity.definitely_no_nulls()
             && self.inputs.iter().all(|input| batch_const(input).is_some())

vortex-array/src/scalar_fn/unstable/row/batch/mod.rs

@@ -5,7 +5,7 @@
 //!
 //! A batch is the set of same-length input columns supplied in one scalar-function call. A row
 //! function handles typed values for one logical row. This module adds the columnar concerns around
-//! that row function: planning the output and null strategy, preserving batch constants,
+//! that row function: planning the output and null handling, preserving batch constants,
 //! propagating strict validity, selecting an execution strategy, and validating the finished
 //! output.
 //!
@@ -46,12 +46,12 @@ pub(crate) struct Batch {
     /// The input dtypes, collected with the columns and reused by both planning and execution.
     arg_dtypes: SmallVec<[DType; 4]>,
 
-    /// The conjoined input validity, so a row of the output is valid iff it is valid in every
-    /// input. Conjoining is lazy, and nothing materializes it unless the null handling asks.
+    /// The conjoined input validity. An output row is valid exactly when it is valid in every
+    /// input. Conjoining is lazy, and null handling materializes the mask only when required.
     validity: Validity,
 
-    /// The dtype the function declares for these inputs, which the kernel's output is reconciled
-    /// against. Already widened to nullable if any input is nullable.
+    /// The declared output dtype, widened to nullable when any input is nullable. Kernel output is
+    /// reconciled against this dtype.
     result_dtype: DType,
 
     /// The non-nullable dtype the dispatched output capability builds, computed while planning.

vortex-array/src/scalar_fn/unstable/row/types/element/output.rs

@@ -19,6 +19,10 @@ pub trait OutputElement: 'static + Sized {
     /// [`OutputSink`]: crate::scalar_fn::unstable::row::OutputSink
     fn element_dtype() -> DType;
 
-    /// Build a column from one value per row. Called once per batch.
+    /// Build an all-valid column from one value per row.
+    ///
+    /// The returned column must contain `values.len()` rows and match
+    /// [`element_dtype`](Self::element_dtype) except for outer nullability. The framework calls
+    /// this method once per batch.
     fn build(values: Vec<Self>) -> ArrayRef;
 }

vortex-array/src/scalar_fn/unstable/row/vtable.rs

@@ -14,8 +14,12 @@ use vortex_error::vortex_ensure_eq;
 use vortex_mask::Mask;
 use vortex_session::VortexSession;
 
+use super::batch::Batch;
+use super::batch::BorrowedExecutionArgs;
 use super::row_fn::RowFn;
 use super::visitor::BatchPlanner;
+use super::visitor::ExecuteRows;
+use super::visitor::ExecuteValidRows;
 use crate::ArrayRef;
 use crate::ExecutionCtx;
 use crate::dtype::DType;
@@ -26,10 +30,6 @@ use crate::scalar_fn::ChildName;
 use crate::scalar_fn::ExecutionArgs;
 use crate::scalar_fn::ScalarFnId;
 use crate::scalar_fn::ScalarFnVTable;
-use crate::scalar_fn::unstable::row::batch::Batch;
-use crate::scalar_fn::unstable::row::batch::BorrowedExecutionArgs;
-use crate::scalar_fn::unstable::row::visitor::ExecuteRows;
-use crate::scalar_fn::unstable::row::visitor::ExecuteValidRows;
 
 impl<F: RowFn> ScalarFnVTable for F {
     type Options = F::Options;