minor: document EquivalenceProperties::project

[zhuqi-lucas]

Rationale for this change

EquivalenceProperties::project is a central, widely-called method, but its doc comment was a single line ("Projects the equivalences within according to mapping and output_schema"). That does not convey that it carries orderings, the equivalence group, and constraints through the mapping, nor the key subtlety that an ordering is preserved only through an order-preserving expression (SortProperties). This tripped me up while reasoning about why an ordering survived a projection containing computed expressions, so I expanded the docs.

What changes are included in this PR?

Documentation only. Expands the rustdoc on EquivalenceProperties::project to describe:

• it carries orderings, the equivalence group, and constraints through the mapping (not just a column-index remap);
• orderings survive only through order-preserving expressions, determined from each expression's SortProperties (e.g. preserved through c + 1, dropped through abs(c); compound orderings like a + b map to a_new + b_new);
• expressions/orderings not representable in output_schema are dropped.

Are these changes tested?

No code change. cargo doc -p datafusion-physical-expr --no-deps builds cleanly with RUSTDOCFLAGS="-D warnings".

Are there any user-facing changes?

Documentation only.

[Copilot]

Pull request overview

Note

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Expands the rustdoc for EquivalenceProperties::project to clarify the semantics of how equivalence properties survive projection, especially around ordering preservation via order-preserving expressions.

Changes:

• Rewrites the method doc comment to describe how orderings, equivalence classes, and constraints are projected.
• Documents the key condition that orderings are only preserved through order-preserving expressions determined by SortProperties.
• Notes that non-representable expressions/orderings are dropped when they can’t be expressed in the projected schema.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.87%. Comparing base (62650ef) to head (4d00799).

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #24063      +/-   ##
==========================================
- Coverage   80.87%   80.87%   -0.01%     
==========================================
  Files        1101     1101              
  Lines      375765   375765              
  Branches   375765   375765              
==========================================
- Hits       303915   303904      -11     
- Misses      53747    53753       +6     
- Partials    18103    18108       +5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.