improve comments.

datafusion/expr-common/src/groups_accumulator.rs

@@ -45,10 +45,10 @@ pub enum EmitTo {
     /// Emit next block in the blocked managed groups
     ///
     /// The flag's meaning:
-    /// - `true` represents it will be added new groups again,
-    ///   we don't need to shift the values down.
-    /// - `false` represents new groups still be possible to be
-    ///   added, and we need to shift the values down.
+    ///   - `true` represents new groups still will be added,
+    ///     and we need to shift the values down.
+    ///   - `false` represents no new groups will be added again,
+    ///     and we don't need to shift the values down.
     NextBlock(bool),
 }
 
@@ -121,8 +121,8 @@ impl EmitTo {
 ///     It will grow constantly when more and more values are inserted,
 ///     that leads to a considerable amount of copying, and finally a bad performance.
 ///
-///   - Blocked, the values in them will be managed with multiple `Vec`s.
-///     When the block is large enough, a new block will be allocated and used
+///   - Blocked(block_size), the values in them will be managed with multiple `Vec`s.
+///     When the block is large enough(reach block_size), a new block will be allocated and used
 ///     for inserting. Obviously, this strategy can avoid copying and get a good performance.
 #[derive(Debug, Clone, Copy)]
 pub enum GroupStatesMode {
@@ -407,6 +407,7 @@ pub trait GroupsAccumulator: Send {
     }
 
     /// Switch the accumulator to flat or blocked mode.
+    /// You can see detail about the mode on [GroupStatesMode].
     ///
     /// After switching mode, all data in previous mode will be cleared.
     fn switch_to_mode(&mut self, mode: GroupStatesMode) -> Result<()> {

datafusion/functions-aggregate-common/src/aggregate/groups_accumulator.rs

@@ -447,7 +447,7 @@ pub fn ensure_enough_room_for_values<T: Clone>(
                 .unwrap()
                 .resize(total_num_groups, default_value);
         }
-        // It blocked mode, we ensure the blks are enough first,
+        // In blocked mode, we ensure the blks are enough first,
         // and then ensure slots in blks are enough.
         GroupStatesMode::Blocked(blk_size) => {
             let (mut cur_blk_idx, exist_slots) = if values.num_blocks() > 0 {

datafusion/functions-aggregate-common/src/aggregate/groups_accumulator/accumulate.rs

@@ -356,7 +356,7 @@ impl NullState {
     }
 }
 
-/// Similar as the [NullState] but supported the blocked version accumulator
+/// Similar as the [NullState] but designed for blocked version accumulator
 #[derive(Debug)]
 pub struct BlockedNullState {
     /// Have we seen any non-filtered input values for `group_index`?
@@ -717,7 +717,7 @@ fn initialize_builder(
     builder
 }
 
-/// Similar as the [initialize_builder] but supported the blocked version accumulator
+/// Similar as the [initialize_builder] but designed for the blocked version accumulator
 fn ensure_enough_room_for_nulls(
     builder_blocks: &mut Blocks<BooleanBufferBuilder>,
     mode: GroupStatesMode,
@@ -741,7 +741,7 @@ fn ensure_enough_room_for_nulls(
                 builder.append_n(new_groups, default_value);
             }
         }
-        // It blocked mode, we ensure the blks are enough first,
+        // In blocked mode, we ensure the blks are enough first,
         // and then ensure slots in blks are enough.
         GroupStatesMode::Blocked(blk_size) => {
             let (mut cur_blk_idx, exist_slots) = if builder_blocks.num_blocks() > 0 {

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

@@ -59,6 +59,7 @@ pub trait GroupValues: Send {
     }
 
     /// Switch the group values to flat or blocked mode.
+    /// You can see detail about the mode on [GroupStatesMode].
     ///
     /// After switching mode, all data in previous mode will be cleared.
     fn switch_to_mode(&mut self, mode: GroupStatesMode) -> Result<()> {