Document the relationship between FileFormat::projection / FileFormat::filter and FileScanConfig::output_ordering (#20196)

## Which issue does this PR close?

- closes #20173
- Similar to #20188

## Rationale for this change

I spent a long time trying to figure out what was going on in our fork
after
a DataFusion 52 upgrade, and the root cause was that the output_ordering
in DataFusion
52 does *NOT* include the projection (more details here
#20173 (comment))

This was not clear to me from the DataFusion code or documentation, and
I think
it would be helpful to clarify this in the documentation.


## What changes are included in this PR?

1. Document FileScanConfig::output_ordering better


## Are these changes tested?

<!--
We typically require tests for all PRs in order to:
1. Prevent the code from being accidentally broken by subsequent changes
2. Serve as another way to document the expected behavior of the code

If tests are not included in your PR, please explain why (for example,
are they covered by existing tests)?
-->

## Are there any user-facing changes?

<!--
If there are user-facing changes then we may require documentation to be
updated before approving the PR.
-->

<!--
If there are any breaking changes to public APIs, please add the `api
change` label.
-->

Author: alamb

datafusion/datasource/src/file_scan_config.rs

@@ -168,7 +168,13 @@ pub struct FileScanConfig {
     /// correct results (e.g., for `ORDER BY ... LIMIT` queries). When `false`,
     /// DataFusion may reorder file processing for optimization without affecting correctness.
     pub preserve_order: bool,
-    /// All equivalent lexicographical orderings that describe the schema.
+    /// All equivalent lexicographical output orderings of this file scan, in terms of
+    /// [`FileSource::table_schema`]. See [`FileScanConfigBuilder::with_output_ordering`] for more
+    /// details.
+    ///
+    /// [`Self::eq_properties`] uses this information along with projection
+    /// and filtering information to compute the effective
+    /// [`EquivalenceProperties`]
     pub output_ordering: Vec<LexOrdering>,
     /// File compression type
     pub file_compression_type: FileCompressionType,
@@ -441,6 +447,13 @@ impl FileScanConfigBuilder {
     }
 
     /// Set the output ordering of the files
+    ///
+    /// The expressions are in terms of the entire table schema (file schema +
+    /// partition columns), before any projection or filtering from the file
+    /// scan is applied.
+    ///
+    /// This is used for optimization purposes, e.g. to determine if a file scan
+    /// can satisfy an `ORDER BY` without an additional sort.
     pub fn with_output_ordering(mut self, output_ordering: Vec<LexOrdering>) -> Self {
         self.output_ordering = output_ordering;
         self
@@ -716,6 +729,9 @@ impl DataSource for FileScanConfig {
         Partitioning::UnknownPartitioning(self.file_groups.len())
     }
 
+    /// Computes the effective equivalence properties of this file scan, taking
+    /// into account the file schema, any projections or filters applied by the
+    /// file source, and the output ordering.
     fn eq_properties(&self) -> EquivalenceProperties {
         let schema = self.file_source.table_schema().table_schema();
         let mut eq_properties = EquivalenceProperties::new_with_orderings(