update docstrings

Author: adriangb

datafusion/optimizer/src/push_down_sort.rs

@@ -32,21 +32,18 @@ use datafusion_expr::{Expr, LogicalPlanContext, ScanOrdering, SortExpr};
 /// Optimization rule that pushes sort expressions down to table scans
 /// when the sort can potentially be optimized by the table provider.
 ///
-/// This rule looks for `Sort -> TableScan` patterns and moves the sort
-/// expressions into the `TableScan.preferred_ordering` field, allowing
-/// table providers to potentially optimize the scan based on sort requirements.
+/// This rule carries sort expressions down through nodes that we know are safe to push
+/// sorts though such as `Projection`, `Filter`, `Repartition` and `Limit`.
+/// It stops when it hits a `TableScan` (where it attaches the sort expressions to the scan)
+/// or any other node type that cannot pass down sort expressions (e.g. `Aggregate`, `Join`, `Union`, etc).
 ///
-/// # Behavior
-///
-/// The optimizer preserves the original `Sort` node as a fallback while passing
-/// the ordering preference to the `TableScan` as an optimization hint. This ensures
-/// correctness even if the table provider cannot satisfy the requested ordering.
-///
-/// # Supported Sort Expressions
-///
-/// Currently, only simple column references are supported for pushdown because
-/// table providers typically cannot optimize complex expressions in sort operations.
-/// Complex expressions like `col("a") + col("b")` or function calls are not pushed down.
+/// The optimizer preserves the original `Sort` node; this optimizer does not remove any sorts.
+/// This means that the [`TableProvider`] can choose to ignore the preferred ordering
+/// or only partially satisfy it. The original `Sort` node ensures that the final output
+/// ordering is always correct.
+/// 
+/// Physical optimizer rules can later remove redundant sorts if they can prove
+/// that the output is already sorted as required.
 ///
 /// # Examples
 ///
@@ -56,8 +53,8 @@ use datafusion_expr::{Expr, LogicalPlanContext, ScanOrdering, SortExpr};
 ///   TableScan: test
 ///
 /// After optimization:
-/// Sort: test.a ASC NULLS LAST  -- Preserved as fallback
-///   TableScan: test            -- Now includes preferred_ordering hint
+/// Sort: test.a ASC NULLS LAST 
+///   TableScan: test preferred_ordering=[test.a ASC NULLS LAST]
 /// ```
 #[derive(Default, Debug)]
 pub struct PushDownSort {}
@@ -68,14 +65,6 @@ impl PushDownSort {
     /// # Returns
     ///
     /// A new `PushDownSort` optimizer rule that can be added to the optimization pipeline.
-    ///
-    /// # Examples
-    ///
-    /// ```rust
-    /// use datafusion_optimizer::push_down_sort::PushDownSort;
-    ///
-    /// let rule = PushDownSort::new();
-    /// ```
     pub fn new() -> Self {
         Self {}
     }