Apply suggestions from code review

Co-authored-by: Andrew Lamb <andrew@nerdnetworks.org>

Author: adriangb

datafusion/catalog/src/table.rs

@@ -470,8 +470,10 @@ impl<'a> ScanArgs<'a> {
         self.limit
     }
 
-    /// Set the statistics the caller would like the provider to answer for
-    /// this scan, if it can do so cheaply.
+    /// Specifies the statistics the caller may use when optimizing the query.
+    ///
+    /// This is intended for to allow the provider to cheaply provide statistics that may help
+    /// such as those it has in an in memory catalog or from some other metadata source. 
     ///
     /// Providers read these via [`Self::statistics_requests()`]; anything a
     /// provider cannot answer cheaply it simply ignores. DataFusion's own
@@ -487,6 +489,8 @@ impl<'a> ScanArgs<'a> {
     }
 
     /// Get the statistics requests for the scan. Empty if none were set.
+    ///
+    /// See [`Self::with_statistics_requests`] for more details
     pub fn statistics_requests(&self) -> &'a [StatisticsRequest] {
         self.statistics_requests
     }

datafusion/expr/src/logical_plan/plan.rs

@@ -2796,16 +2796,9 @@ pub struct TableScan {
     pub fetch: Option<usize>,
     /// Statistics the planner would like the provider to answer for this
     /// scan, typically attached by a custom optimizer rule from the
-    /// surrounding plan shape (e.g. Min/Max for sort keys). Threaded into
-    /// the table provider via `ScanArgs::statistics_requests` at
-    /// physical-planning time. Advisory and empty by default; DataFusion's
-    /// own rules never populate it.
+    /// surrounding plan (e.g. Min/Max for sort keys). 
     ///
-    /// A [`BTreeSet`], not a `Vec`: optimizer rules run to a fixpoint, so the
-    /// collection must be idempotent under re-derivation — a rule `insert`s
-    /// the requests it wants and re-running is a no-op (and composes with
-    /// other rules) without each rule having to dedupe. The ordering also
-    /// keeps the resulting plan deterministic.
+    /// A [`BTreeSet`], not a `Vec` to keep the resulting plan deterministic.
     pub statistics_requests: BTreeSet<StatisticsRequest>,
 }