alamb opened a new pull request, #27266: URL: https://github.com/apache/datafusion/pull/27266
## Which issue does this PR close? - N/A, documentation only. ## Rationale for this change While reviewing https://github.com/apache/datafusion/pull/27191 I was researching how `SortKeyWalk` (added in https://github.com/apache/datafusion/pull/26853) decides whether known orderings satisfy a sort requirement, and wanted to write down what I learned so others do not have to repeat it. The existing doc stated the rules but did not define the terms before using them, and had no example a reader could trace step by step. ## What changes are included in this PR? Rustdoc only, in `datafusion/physical-expr/src/equivalence/properties/walk.rs`: - An introduction that defines *pinned*, *fixed*, *implied ordering* and *head* in terms of what each means for the rows still in play, with a note on how pinned differs from fixed and from a constant. - Worked examples as step tables showing, for each requirement key, what is pinned, where each ordering's head is, and the outcome: a prefix match, two orderings combining to satisfy `[a, b, c]` (with a data table showing why that is sound), a failing case, a head that moves in two orderings at once, a head that does not move, and an implied ordering found through `c = CAST(a AS BIGINT)`. - Field docs for `pinned`, `implied` and `head_idxs` that say what each index and value refers to. - Links to the `EquivalenceProperties` sections that define normal form and requirement checking. Split out of https://github.com/apache/datafusion/pull/27234. Companion splits: https://github.com/apache/datafusion/pull/27237, https://github.com/apache/datafusion/pull/27238 and https://github.com/apache/datafusion/pull/27250. The section links here (`#normal-form`, `#checking-whether-a-requirement-is-satisfied`) point at headings added in #27250. ## What is the testing strategy for this PR? No code changes. `cargo doc` with `-D warnings` passes with and without `--document-private-items` (the struct is `pub(super)`), and clippy passes. ## Are there any user-facing changes? No. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
