fix: improve GroupOrdering docs (#20994)

## Which issue does this PR close?

<!--
We generally require a GitHub issue to be filed for all bug fixes and
enhancements and this helps us generate change logs for our releases.
You can link an issue to this PR using the GitHub syntax. For example
`Closes #123` indicates that this PR will close issue #123.
-->

- Closes #.

## Rationale for this change

While working on #20559 I ran
across some comments that were outdated / could be improved

## What changes are included in this PR?

Improve comments

## Are these changes tested?

By CI
## Are there any user-facing changes?

Just better docs

Author: alamb

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

@@ -52,8 +52,8 @@ impl GroupOrdering {
         }
     }
 
-    /// Returns how many groups be emitted while respecting the current ordering
-    /// guarantees, or `None` if no data can be emitted
+    /// Returns how many groups can be emitted while respecting the current
+    /// ordering guarantees, or `None` if no data can be emitted.
     pub fn emit_to(&self) -> Option<EmitTo> {
         match self {
             GroupOrdering::None => None,
@@ -84,7 +84,7 @@ impl GroupOrdering {
         }
     }
 
-    /// Updates the state the input is done
+    /// Updates the state to indicate that the input is complete.
     pub fn input_done(&mut self) {
         match self {
             GroupOrdering::None => {}
@@ -93,8 +93,8 @@ impl GroupOrdering {
         }
     }
 
-    /// remove the first n groups from the internal state, shifting
-    /// all existing indexes down by `n`
+    /// Removes the first `n` groups from the internal state, shifting all
+    /// existing indexes down by `n`.
     pub fn remove_groups(&mut self, n: usize) {
         match self {
             GroupOrdering::None => {}
@@ -103,16 +103,14 @@ impl GroupOrdering {
         }
     }
 
-    /// Called when new groups are added in a batch
+    /// Called when new groups are added in a batch.
     ///
-    /// * `total_num_groups`: total number of groups (so max
-    ///   group_index is total_num_groups - 1).
-    ///
-    /// * `group_values`: group key values for *each row* in the batch
+    /// * `batch_group_values`: group key values for each row in the batch
     ///
     /// * `group_indices`: indices for each row in the batch
     ///
-    /// * `hashes`: hash values for each row in the batch
+    /// * `total_num_groups`: total number of groups (so max
+    ///   group_index is total_num_groups - 1).
     pub fn new_groups(
         &mut self,
         batch_group_values: &[ArrayRef],
@@ -135,7 +133,7 @@ impl GroupOrdering {
         Ok(())
     }
 
-    /// Return the size of memory used by the ordering state, in bytes
+    /// Returns the size of memory used by the ordering state, in bytes.
     pub fn size(&self) -> usize {
         size_of::<Self>()
             + match self {