more better docs

Author: alamb

datafusion/expr/src/groups_accumulator.rs

@@ -128,6 +128,9 @@ pub trait GroupsAccumulator: Send {
     /// Returns the intermediate aggregate state for this accumulator,
     /// used for multi-phase grouping, resetting its internal state.
     ///
+    /// See [`Accumulator::state`] for more information on multi-phase
+    /// aggregation.
+    ///
     /// For example, `AVG` might return two arrays: `SUM` and `COUNT`
     /// but the `MIN` aggregate would just return a single array.
     ///
@@ -159,7 +162,9 @@ pub trait GroupsAccumulator: Send {
     ) -> Result<()>;
 
     /// Amount of memory used to store the state of this accumulator,
-    /// in bytes. This function is called once per batch, so it should
-    /// be `O(n)` to compute, not `O(num_groups)`
+    /// in bytes.
+    ///
+    /// This function is called once per batch, so it should be `O(n)` to
+    /// compute, not `O(num_groups)`
     fn size(&self) -> usize;
 }

datafusion/physical-plan/src/aggregates/mod.rs

@@ -72,8 +72,7 @@ pub enum AggregateMode {
     /// Final aggregate that produces a single partition of output by combining
     /// the output of multiple partial aggregates.
     ///
-    /// This is the second phase of a
-    /// multi-phase aggregation.
+    /// This is the second phase of a multi-phase aggregation.
     Final,
     /// Final aggregate that works on pre-partitioned data.
     ///
@@ -92,7 +91,8 @@ pub enum AggregateMode {
     /// as opposed to Partial / Final modes which apply the logical aggregation using
     /// two operators.
     ///
-    /// This mode requires that the input is partitioned by group key (like FinalPartitioned)
+    /// This mode requires that the input is partitioned by group key (like
+    /// FinalPartitioned)
     SinglePartitioned,
 }
 

datafusion/physical-plan/src/aggregates/row_hash.rs

@@ -137,7 +137,7 @@ struct SpillState {
 /// of `x` and one accumulator for `SUM(y)`, specialized for the data
 /// type of `y`.
 ///
-/// # Description
+/// # Discussion
 ///
 /// [`group_values`] does not store any aggregate state inline. It only
 /// assigns "group indices", one for each (distinct) group value. The
@@ -160,9 +160,12 @@ struct SpillState {
 /// As described on [`Accumulator::state`], this operator is used in the context
 /// "multi-phase" grouping when the mode is [`AggregateMode::Partial`].
 ///
+/// An important optimization for partial aggregation
+///
+///
 /// [`Accumulator::state`]: datafusion_expr::Accumulator::state
 ///
-/// # Spilling
+/// # Spilling (to disk)
 ///
 /// The sizes of group values and accumulators can become large. Before that causes out of memory,
 /// this hash aggregator outputs partial states early for partial aggregation or spills to local