docs: clarify what PushedDown::Yes and PushedDown::No mean

`PushedDown::Yes` means the child applies the predicate exactly, so the
parent does not need to evaluate it again. `PushedDown::No` means the parent
must still evaluate it. A child that replies `No` can still use the filter
in an inexact way, for example for statistics pruning. Document this.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: adriangb

datafusion/physical-plan/src/filter_pushdown.rs

@@ -123,11 +123,32 @@ impl PushedDownPredicate {
 }
 
 /// Discriminant for the result of pushing down a filter into a child node.
+///
+/// This answers one question for the parent: "do I still have to evaluate
+/// this filter?". It does not describe how the child uses the filter.
+///
+/// A child that replies [`PushedDown::No`] may still keep the filter and use
+/// it in an inexact way, for example to prune files, row groups or pages with
+/// statistics. `ParquetSource` does this when `pushdown_filters` is disabled.
+/// There is no separate "inexact" state: whether or not the child uses the
+/// filter, the parent must evaluate it, so the parent's action is the same.
+///
+/// Producers of filters that are not needed for correctness (for example
+/// dynamic filters from `HashJoinExec` or TopK) do not use this reply to
+/// find out if a consumer exists. They check whether the filter is present
+/// in the child subtree instead (see
+/// [`plan_contains_expression_id`](crate::execution_plan::plan_contains_expression_id)).
 #[derive(Debug, Clone, Copy)]
 pub enum PushedDown {
-    /// The predicate was successfully pushed down into the child node.
+    /// The child guarantees that it applies the predicate exactly: it never
+    /// produces a row for which the predicate is not true. The parent does
+    /// not need to evaluate the predicate again.
     Yes,
-    /// The predicate could not be pushed down into the child node.
+    /// The child does not guarantee that it applies the predicate exactly,
+    /// so the parent must still evaluate it.
+    ///
+    /// The child may ignore the predicate, or it may use it in an inexact
+    /// way, for example for statistics pruning.
     No,
 }