docs: clarify what PushedDown::Yes and PushedDown::No mean (#25670)

## Which issue does this PR close?

- Related to #18856 and #24528. This PR does not change the API. It only
documents the two states that exist.

## Rationale for this change

The docs say `PushedDown::No` means "the predicate could not be pushed
down into the child node". This reads as "the child ignores the filter".
But a child that replies `No` can still use the filter, for example for
statistics pruning.

## What changes are included in this PR?

Doc comments on `PushedDown`:

| Reply | Must the parent evaluate the filter? | Can the child use the
filter? |
|---|---|---|
| `Yes` | No. The child applies it exactly. | Yes, exactly |
| `No` | Yes | Yes, in an inexact way (for example statistics pruning),
or not at all |

## What is the testing strategy for this PR?

Documentation only. `cargo doc -p datafusion-physical-plan` builds with
`-D warnings`.

## Are there any user-facing changes?

No.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: adriangb

datafusion/physical-plan/src/filter_pushdown.rs

@@ -123,11 +123,24 @@ impl PushedDownPredicate {
 }
 
 /// Discriminant for the result of pushing down a filter into a child node.
+///
+/// This tells the parent whether it still has to evaluate the filter. It does
+/// not tell the parent how, or if, the child uses the filter.
+///
+/// For example, a child that replies [`PushedDown::No`] can still keep the
+/// filter and use it in an inexact way, such as to prune files, row groups or
+/// pages with statistics.
 #[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,
 }