docs: more docs around AnalysisExpr and boolean operators (#3508)

Signed-off-by: Daniel King <[email protected]>

Author: danking

vortex-array/src/compute/boolean.rs

@@ -14,31 +14,42 @@ use crate::{Array, ArrayRef};
 
 /// Point-wise logical _and_ between two Boolean arrays.
 ///
-/// This method uses Arrow-style null propagation rather than the Kleene logic semantics.
+/// This method uses Arrow-style null propagation rather than the Kleene logic semantics. This
+/// semantics is also known as "Bochvar logic" and "weak Kleene logic".
+///
+/// See also [BooleanOperator::And]
 pub fn and(lhs: &dyn Array, rhs: &dyn Array) -> VortexResult<ArrayRef> {
     boolean(lhs, rhs, BooleanOperator::And)
 }
 
 /// Point-wise Kleene logical _and_ between two Boolean arrays.
+///
+/// See also [BooleanOperator::AndKleene]
 pub fn and_kleene(lhs: &dyn Array, rhs: &dyn Array) -> VortexResult<ArrayRef> {
     boolean(lhs, rhs, BooleanOperator::AndKleene)
 }
 
 /// Point-wise logical _or_ between two Boolean arrays.
 ///
-/// This method uses Arrow-style null propagation rather than the Kleene logic semantics.
+/// This method uses Arrow-style null propagation rather than the Kleene logic semantics. This
+/// semantics is also known as "Bochvar logic" and "weak Kleene logic".
+///
+/// See also [BooleanOperator::Or]
 pub fn or(lhs: &dyn Array, rhs: &dyn Array) -> VortexResult<ArrayRef> {
     boolean(lhs, rhs, BooleanOperator::Or)
 }
 
 /// Point-wise Kleene logical _or_ between two Boolean arrays.
+///
+/// See also [BooleanOperator::OrKleene]
 pub fn or_kleene(lhs: &dyn Array, rhs: &dyn Array) -> VortexResult<ArrayRef> {
     boolean(lhs, rhs, BooleanOperator::OrKleene)
 }
 
 /// Point-wise logical operator between two Boolean arrays.
 ///
-/// This method uses Arrow-style null propagation rather than the Kleene logic semantics.
+/// This method uses Arrow-style null propagation rather than the Kleene logic semantics. This
+/// semantics is also known as "Bochvar logic" and "weak Kleene logic".
 pub fn boolean(lhs: &dyn Array, rhs: &dyn Array, op: BooleanOperator) -> VortexResult<ArrayRef> {
     BOOLEAN_FN
         .invoke(&InvocationArgs {
@@ -181,11 +192,46 @@ impl ComputeFnVTable for Boolean {
     }
 }
 
+/// Operations over the nullable Boolean values.
+///
+/// All three operators accept and produce values from the set {true, false, and null}.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum BooleanOperator {
+    /// Logical and, unless either value is null, in which case the result is null.
+    ///
+    /// | A ∧ B |       | **B** |       |       |
+    /// |:-----:|:-----:|:-----:|:-----:|:-----:|
+    /// |       |       | **F** | **U** | **T** |
+    /// | **A** | **F** | F     | U     | F     |
+    /// |       | **U** | U     | U     | U     |
+    /// |       | **T** | F     | U     | T     |
     And,
+    /// [Kleene (three-valued) logical and](https://en.wikipedia.org/wiki/Three-valued_logic#Kleene_and_Priest_logics).
+    ///
+    /// | A ∧ B |       | **B** |       |       |
+    /// |:-----:|:-----:|:-----:|:-----:|:-----:|
+    /// |       |       | **F** | **U** | **T** |
+    /// | **A** | **F** | F     | F     | F     |
+    /// |       | **U** | F     | U     | U     |
+    /// |       | **T** | F     | U     | T     |
     AndKleene,
+    /// Logical or, unless either value is null, in which case the result is null.
+    ///
+    /// | A ∨ B |       | **B** |       |       |
+    /// |:-----:|:-----:|:-----:|:-----:|:-----:|
+    /// |       |       | **F** | **U** | **T** |
+    /// | **A** | **F** | F     | U     | T     |
+    /// |       | **U** | U     | U     | U     |
+    /// |       | **T** | T     | U     | T     |
     Or,
+    /// [Kleene (three-valued) logical or](https://en.wikipedia.org/wiki/Three-valued_logic#Kleene_and_Priest_logics).
+    ///
+    /// | A ∨ B |       | **B** |       |       |
+    /// |:-----:|:-----:|:-----:|:-----:|:-----:|
+    /// |       |       | **F** | **U** | **T** |
+    /// | **A** | **F** | F     | U     | T     |
+    /// |       | **U** | U     | U     | T     |
+    /// |       | **T** | T     | T     | T     |
     OrKleene,
     // AndNot,
     // AndNotKleene,

vortex-expr/src/analysis.rs

@@ -35,15 +35,20 @@ pub trait AnalysisExpr {
         None
     }
 
-    /// If an expression is returned, its value is an upper bound on the value of `expr`.
+    /// An expression for the upper non-null bound of this expression, if available.
     ///
-    /// We may return `None` for values which have no upper bound or values for which knowing the
-    /// upper bound is difficult.
+    /// This function returns None if there is no upper bound or it is difficult to compute.
+    ///
+    /// The returned expression evaluates to null if the maximum value is unknown. In that case, you
+    /// _must not_ assume the array is empty _nor_ may you assume the array only contains non-null
+    /// values.
     fn max(&self, _catalog: &mut dyn StatsCatalog) -> Option<ExprRef> {
         None
     }
-    /// If an expression is returned, its value is an upper bound on the value of `expr`.
-    /// see `AnalysisExpr::max`
+
+    /// An expression for the lower non-null bound of this expression, if available.
+    ///
+    /// See [AnalysisExpr::max] for important details.
     fn min(&self, _catalog: &mut dyn StatsCatalog) -> Option<ExprRef> {
         None
     }

vortex-expr/src/exprs/operators.rs

@@ -3,6 +3,10 @@ use std::fmt::{Display, Formatter};
 
 use vortex_array::compute;
 
+/// Equalities, inequalities, and boolean operations over possibly null values.
+///
+/// For the equalities and inequalities, if either side is null, the result is null. The Boolean
+/// operators obey [Kleene (three-valued) logic](https://en.wikipedia.org/wiki/Three-valued_logic#Kleene_and_Priest_logics).
 #[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Hash)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub enum Operator {

vortex-layout/src/layouts/zoned/reader.rs

@@ -250,12 +250,15 @@ impl LayoutReader for ZonedReader {
 struct ZoneMapPruningEvaluation {
     name: Arc<str>,
     expr: ExprRef,
+    /// A mask indicating zones which have no matching values.
+    ///
+    /// A false value indicates the corresponding zone may have a matching value.
     pruning_mask_future: SharedPruningResult,
-    // The set of zone IDs that are available to the evaluation.
+    /// The set of zone IDs that are available to the evaluation.
     zone_range: Range<u64>,
-    // The lengths of each zone in the zone_range.
+    /// The lengths of each zone in the zone_range.
     zone_lengths: Vec<usize>,
-    // The evaluation of the data child.
+    /// The evaluation of the data child.
     data_eval: Box<dyn PruningEvaluation>,
 }