chore: Add docs to the stand alone expr creation functions (#4253)

Signed-off-by: Adam Gutglick <[email protected]>

Author: AdamGS

vortex-cxx/src/expr.rs

@@ -12,7 +12,7 @@ pub(crate) struct Expr {
 
 pub(crate) fn literal(scalar: Box<Scalar>) -> Box<Expr> {
     Box::new(Expr {
-        inner: vortex::expr::literal::lit(scalar.inner),
+        inner: vortex::expr::lit(scalar.inner),
     })
 }
 

vortex-expr/src/analysis.rs

@@ -29,7 +29,7 @@ pub trait AnalysisExpr {
     /// necessarily true: even if the falsification evaluates to false, `e` need not evaluate to
     /// true on all records.
     ///
-    /// The `StatsCatalog` can be used to constrain or rename stats used in the final expr.
+    /// The [`StatsCatalog`] can be used to constrain or rename stats used in the final expr.
     ///
     /// # Examples
     ///

vortex-expr/src/dyn_traits.rs

@@ -5,7 +5,7 @@ use std::any::Any;
 
 // TODO(adam): Look into having a similar setup as dyn-hash that will allow deriving `PartialEq` for structs
 // that have `Arc<dyn Trait>` fields.
-/// Allows comparing dyn-compatible objects, like [`ExprRef`].
+/// Allows comparing dyn-compatible objects, like [`ExprRef`](crate::ExprRef).
 pub trait DynEq {
     fn dyn_eq(&self, other: &dyn Any) -> bool;
 }

vortex-expr/src/exprs/between.rs

@@ -177,6 +177,21 @@ impl Display for BetweenExpr {
 
 impl AnalysisExpr for BetweenExpr {}
 
+/// Creates an expression that checks if values are between two bounds.
+///
+/// Returns a boolean array indicating which values fall within the specified range.
+/// The comparison strictness is controlled by the options parameter.
+///
+/// ```rust
+/// # use vortex_array::compute::BetweenOptions;
+/// # use vortex_array::compute::StrictComparison;
+/// # use vortex_expr::{between, lit, root};
+/// let opts = BetweenOptions {
+///     lower_strict: StrictComparison::NonStrict,
+///     upper_strict: StrictComparison::NonStrict,
+/// };
+/// let expr = between(root(), lit(10), lit(20), opts);
+/// ```
 pub fn between(arr: ExprRef, lower: ExprRef, upper: ExprRef, options: BetweenOptions) -> ExprRef {
     BetweenExpr::new(arr, lower, upper, options).into_expr()
 }

vortex-expr/src/exprs/binary.rs

@@ -268,17 +268,16 @@ impl AnalysisExpr for BinaryExpr {
     }
 }
 
-/// Create a new `BinaryExpr` using the `Eq` operator.
+/// Create a new [`BinaryExpr`] using the [`Eq`](crate::Operator::Eq) operator.
 ///
 /// ## Example usage
 ///
 /// ```
-/// use vortex_array::arrays::{BoolArray, PrimitiveArray };
-/// use vortex_array::{Array, IntoArray, ToCanonical};
-/// use vortex_array::validity::Validity;
-/// use vortex_buffer::buffer;
-/// use vortex_expr::{eq, root, lit, Scope};
-///
+/// # use vortex_array::arrays::{BoolArray, PrimitiveArray };
+/// # use vortex_array::{Array, IntoArray, ToCanonical};
+/// # use vortex_array::validity::Validity;
+/// # use vortex_buffer::buffer;
+/// # use vortex_expr::{eq, root, lit, Scope};
 /// let xs = PrimitiveArray::new(buffer![1i32, 2i32, 3i32], Validity::NonNullable);
 /// let result = eq(root(), lit(3)).evaluate(&Scope::new(xs.to_array())).unwrap();
 ///
@@ -291,17 +290,16 @@ pub fn eq(lhs: ExprRef, rhs: ExprRef) -> ExprRef {
     BinaryExpr::new(lhs, Operator::Eq, rhs).into_expr()
 }
 
-/// Create a new `BinaryExpr` using the `NotEq` operator.
+/// Create a new [`BinaryExpr`] using the [`NotEq`](crate::Operator::NotEq) operator.
 ///
 /// ## Example usage
 ///
 /// ```
-/// use vortex_array::arrays::{BoolArray, PrimitiveArray };
-/// use vortex_array::{IntoArray, ToCanonical};
-/// use vortex_array::validity::Validity;
-/// use vortex_buffer::buffer;
-/// use vortex_expr::{root, lit, not_eq, Scope};
-///
+/// # use vortex_array::arrays::{BoolArray, PrimitiveArray };
+/// # use vortex_array::{IntoArray, ToCanonical};
+/// # use vortex_array::validity::Validity;
+/// # use vortex_buffer::buffer;
+/// # use vortex_expr::{root, lit, not_eq, Scope};
 /// let xs = PrimitiveArray::new(buffer![1i32, 2i32, 3i32], Validity::NonNullable);
 /// let result = not_eq(root(), lit(3)).evaluate(&Scope::new(xs.to_array())).unwrap();
 ///
@@ -314,17 +312,16 @@ pub fn not_eq(lhs: ExprRef, rhs: ExprRef) -> ExprRef {
     BinaryExpr::new(lhs, Operator::NotEq, rhs).into_expr()
 }
 
-/// Create a new `BinaryExpr` using the `Gte` operator.
+/// Create a new [`BinaryExpr`] using the [`Gte`](crate::Operator::Gte) operator.
 ///
 /// ## Example usage
 ///
 /// ```
-/// use vortex_array::arrays::{BoolArray, PrimitiveArray };
-/// use vortex_array::{IntoArray, ToCanonical};
-/// use vortex_array::validity::Validity;
-/// use vortex_buffer::buffer;
-/// use vortex_expr::{gt_eq, root, lit, Scope};
-///
+/// # use vortex_array::arrays::{BoolArray, PrimitiveArray };
+/// # use vortex_array::{IntoArray, ToCanonical};
+/// # use vortex_array::validity::Validity;
+/// # use vortex_buffer::buffer;
+/// # use vortex_expr::{gt_eq, root, lit, Scope};
 /// let xs = PrimitiveArray::new(buffer![1i32, 2i32, 3i32], Validity::NonNullable);
 /// let result = gt_eq(root(), lit(3)).evaluate(&Scope::new(xs.to_array())).unwrap();
 ///
@@ -337,17 +334,16 @@ pub fn gt_eq(lhs: ExprRef, rhs: ExprRef) -> ExprRef {
     BinaryExpr::new(lhs, Operator::Gte, rhs).into_expr()
 }
 
-/// Create a new `BinaryExpr` using the `Gt` operator.
+/// Create a new [`BinaryExpr`] using the [`Gt`](crate::Operator::Gt) operator.
 ///
 /// ## Example usage
 ///
 /// ```
-/// use vortex_array::arrays::{BoolArray, PrimitiveArray };
-/// use vortex_array::{IntoArray, ToCanonical};
-/// use vortex_array::validity::Validity;
-/// use vortex_buffer::buffer;
-/// use vortex_expr::{gt, root, lit, Scope};
-///
+/// # use vortex_array::arrays::{BoolArray, PrimitiveArray };
+/// # use vortex_array::{IntoArray, ToCanonical};
+/// # use vortex_array::validity::Validity;
+/// # use vortex_buffer::buffer;
+/// # use vortex_expr::{gt, root, lit, Scope};
 /// let xs = PrimitiveArray::new(buffer![1i32, 2i32, 3i32], Validity::NonNullable);
 /// let result = gt(root(), lit(2)).evaluate(&Scope::new(xs.to_array())).unwrap();
 ///
@@ -360,17 +356,16 @@ pub fn gt(lhs: ExprRef, rhs: ExprRef) -> ExprRef {
     BinaryExpr::new(lhs, Operator::Gt, rhs).into_expr()
 }
 
-/// Create a new `BinaryExpr` using the `Lte` operator.
+/// Create a new [`BinaryExpr`] using the [`Lte`](crate::Operator::Lte) operator.
 ///
 /// ## Example usage
 ///
 /// ```
-/// use vortex_array::arrays::{BoolArray, PrimitiveArray };
-/// use vortex_array::{IntoArray, ToCanonical};
-/// use vortex_array::validity::Validity;
-/// use vortex_buffer::buffer;
-/// use vortex_expr::{root, lit, lt_eq, Scope};
-///
+/// # use vortex_array::arrays::{BoolArray, PrimitiveArray };
+/// # use vortex_array::{IntoArray, ToCanonical};
+/// # use vortex_array::validity::Validity;
+/// # use vortex_buffer::buffer;
+/// # use vortex_expr::{root, lit, lt_eq, Scope};
 /// let xs = PrimitiveArray::new(buffer![1i32, 2i32, 3i32], Validity::NonNullable);
 /// let result = lt_eq(root(), lit(2)).evaluate(&Scope::new(xs.to_array())).unwrap();
 ///
@@ -383,17 +378,16 @@ pub fn lt_eq(lhs: ExprRef, rhs: ExprRef) -> ExprRef {
     BinaryExpr::new(lhs, Operator::Lte, rhs).into_expr()
 }
 
-/// Create a new `BinaryExpr` using the `Lt` operator.
+/// Create a new [`BinaryExpr`] using the [`Lt`](crate::Operator::Lt) operator.
 ///
 /// ## Example usage
 ///
 /// ```
-/// use vortex_array::arrays::{BoolArray, PrimitiveArray };
-/// use vortex_array::{IntoArray, ToCanonical};
-/// use vortex_array::validity::Validity;
-/// use vortex_buffer::buffer;
-/// use vortex_expr::{root, lit, lt, Scope};
-///
+/// # use vortex_array::arrays::{BoolArray, PrimitiveArray };
+/// # use vortex_array::{IntoArray, ToCanonical};
+/// # use vortex_array::validity::Validity;
+/// # use vortex_buffer::buffer;
+/// # use vortex_expr::{root, lit, lt, Scope};
 /// let xs = PrimitiveArray::new(buffer![1i32, 2i32, 3i32], Validity::NonNullable);
 /// let result = lt(root(), lit(3)).evaluate(&Scope::new(xs.to_array())).unwrap();
 ///
@@ -406,15 +400,14 @@ pub fn lt(lhs: ExprRef, rhs: ExprRef) -> ExprRef {
     BinaryExpr::new(lhs, Operator::Lt, rhs).into_expr()
 }
 
-/// Create a new `BinaryExpr` using the `Or` operator.
+/// Create a new [`BinaryExpr`] using the [`Or`](crate::Operator::Or) operator.
 ///
 /// ## Example usage
 ///
 /// ```
-/// use vortex_array::arrays::BoolArray;
-/// use vortex_array::{IntoArray, ToCanonical};
-/// use vortex_expr::{root, lit, or, Scope};
-///
+/// # use vortex_array::arrays::BoolArray;
+/// # use vortex_array::{IntoArray, ToCanonical};
+/// # use vortex_expr::{root, lit, or, Scope};
 /// let xs = BoolArray::from_iter(vec![true, false, true]);
 /// let result = or(root(), lit(false)).evaluate(&Scope::new(xs.to_array())).unwrap();
 ///
@@ -439,15 +432,14 @@ where
     Some(iter.rfold(first, |acc, elem| or(elem, acc)))
 }
 
-/// Create a new `BinaryExpr` using the `And` operator.
+/// Create a new [`BinaryExpr`] using the [`And`](crate::Operator::And) operator.
 ///
 /// ## Example usage
 ///
 /// ```
-/// use vortex_array::arrays::BoolArray;
-/// use vortex_array::{IntoArray, ToCanonical};
-/// use vortex_expr::{and, root, lit, Scope};
-///
+/// # use vortex_array::arrays::BoolArray;
+/// # use vortex_array::{IntoArray, ToCanonical};
+/// # use vortex_expr::{and, root, lit, Scope};
 /// let xs = BoolArray::from_iter(vec![true, false, true]);
 /// let result = and(root(), lit(true)).evaluate(&Scope::new(xs.to_array())).unwrap();
 ///
@@ -482,16 +474,15 @@ where
     iter.reduce(and)
 }
 
-/// Create a new `BinaryExpr` using the `CheckedAdd` operator.
+/// Create a new [`BinaryExpr`] using the [`Add`](crate::Operator::Add) operator.
 ///
 /// ## Example usage
 ///
 /// ```
-/// use vortex_array::IntoArray;
-/// use vortex_array::arrow::IntoArrowArray as _;
-/// use vortex_buffer::buffer;
-/// use vortex_expr::{Scope, checked_add, lit, root};
-///
+/// # use vortex_array::IntoArray;
+/// # use vortex_array::arrow::IntoArrowArray as _;
+/// # use vortex_buffer::buffer;
+/// # use vortex_expr::{Scope, checked_add, lit, root};
 /// let xs = buffer![1, 2, 3].into_array();
 /// let result = checked_add(root(), lit(5))
 ///     .evaluate(&Scope::new(xs.to_array()))

vortex-expr/src/exprs/cast.rs

@@ -108,6 +108,15 @@ impl Display for CastExpr {
 
 impl AnalysisExpr for CastExpr {}
 
+/// Creates an expression that casts values to a target data type.
+///
+/// Converts the input expression's values to the specified target type.
+///
+/// ```rust
+/// # use vortex_dtype::{DType, Nullability, PType};
+/// # use vortex_expr::{cast, root};
+/// let expr = cast(root(), DType::Primitive(PType::I64, Nullability::NonNullable));
+/// ```
 pub fn cast(child: ExprRef, target: DType) -> ExprRef {
     CastExpr::new(child, target).into_expr()
 }

vortex-expr/src/exprs/get_item.rs

@@ -128,10 +128,26 @@ impl GetItemExpr {
     }
 }
 
+/// Creates an expression that accesses a field from the root array.
+///
+/// Equivalent to `get_item(field, root())` - extracts a named field from the input array.
+///
+/// ```rust
+/// # use vortex_expr::col;
+/// let expr = col("name");
+/// ```
 pub fn col(field: impl Into<FieldName>) -> ExprRef {
     GetItemExpr::new(field, root()).into_expr()
 }
 
+/// Creates an expression that extracts a named field from a struct expression.
+///
+/// Accesses the specified field from the result of the child expression.
+///
+/// ```rust
+/// # use vortex_expr::{get_item, root};
+/// let expr = get_item("user_id", root());
+/// ```
 pub fn get_item(field: impl Into<FieldName>, child: ExprRef) -> ExprRef {
     GetItemExpr::new(field, child).into_expr()
 }

vortex-expr/src/exprs/is_null.rs

@@ -96,6 +96,14 @@ impl Display for IsNullExpr {
 
 impl AnalysisExpr for IsNullExpr {}
 
+/// Creates an expression that checks for null values.
+///
+/// Returns a boolean array indicating which positions contain null values.
+///
+/// ```rust
+/// # use vortex_expr::{is_null, root};
+/// let expr = is_null(root());
+/// ```
 pub fn is_null(child: ExprRef) -> ExprRef {
     IsNullExpr::new(child).into_expr()
 }

vortex-expr/src/exprs/list_contains.rs

@@ -105,6 +105,14 @@ impl ListContainsExpr {
     }
 }
 
+/// Creates an expression that checks if a value is contained in a list.
+///
+/// Returns a boolean array indicating whether the value appears in each list.
+///
+/// ```rust
+/// # use vortex_expr::{list_contains, lit, root};
+/// let expr = list_contains(root(), lit(42));
+/// ```
 pub fn list_contains(list: ExprRef, value: ExprRef) -> ExprRef {
     ListContainsExpr::new(list, value).into_expr()
 }

vortex-expr/src/exprs/merge.rs

@@ -171,6 +171,16 @@ impl MergeExpr {
     }
 }
 
+/// Creates an expression that merges struct expressions into a single struct.
+///
+/// Combines fields from all input expressions. If field names are duplicated,
+/// later expressions win. Fields are not recursively merged.
+///
+/// ```rust
+/// # use vortex_dtype::Nullability;
+/// # use vortex_expr::{merge, get_item, root};
+/// let expr = merge([get_item("a", root()), get_item("b", root())], Nullability::NonNullable);
+/// ```
 pub fn merge(
     elements: impl IntoIterator<Item = impl Into<ExprRef>>,
     nullability: Nullability,