feat: update comments and documentation in Cargo.toml and mod.rs

- Clarified spill codec comments in Cargo.toml:50 and Cargo.toml:99 to explain that arrow-ipc is consumed only via the arrow::ipc re-export, addressing potential unused flags from cargo-machete.
- Revised writer doc comment in mod.rs:295 to specify "build-visible during Cargo feature resolution" instead of "compiler-visible."
- Replaced bare commit hash reference with PR #21917 for clarity.
- Added brief notes to the opportunistic serde_json cargo-machete cleanup in Cargo.toml:85 and Cargo.toml:97 to indicate they are unrelated to the spill contract.

Author: kosiew

datafusion-cli/Cargo.toml

@@ -82,7 +82,7 @@ testcontainers-modules = { workspace = true, features = ["minio"] }
 # feature unification with dependencies
 serde_json = { workspace = true, features = ["preserve_order"] }
 
-# Required because we pull serde_json with a feature to get consistent pg display,
-# but its not directly used.
+# Opportunistic cargo-machete cleanup: serde_json is pulled with a feature to get
+# consistent pg display, but is not directly used in this crate.
 [package.metadata.cargo-machete]
 ignored = ["serde_json"]

datafusion/physical-plan/Cargo.toml

@@ -49,12 +49,13 @@ name = "datafusion_physical_plan"
 [dependencies]
 arrow = { workspace = true }
 arrow-data = { workspace = true }
-# Feature-only dep (arrow re-exports this crate as `arrow::ipc`): lz4 and zstd
-# codec support required by IPCStreamWriter in spill/mod.rs. These features must
-# stay in sync with the SpillCompression variants in datafusion-common. Declaring
-# the dependency here makes the contract explicit and local to the crate that owns
-# spill, preventing silent regressions if workspace-level arrow-ipc features are
-# narrowed (see commit 14c18ece4 for a prior regression caused by this coupling).
+# Feature-only dep used only via the `arrow::ipc` re-export (there is no direct
+# `use arrow_ipc` in this crate): lz4 and zstd codec support required by
+# IPCStreamWriter in spill/mod.rs. These features must stay in sync with the
+# SpillCompression variants in datafusion-common. Declaring the dependency here
+# makes the contract explicit and local to the crate that owns spill, preventing
+# silent regressions if workspace-level arrow-ipc features are narrowed (see
+# #21917 for the documented regression guard around this coupling).
 arrow-ipc = { workspace = true, features = ["lz4", "zstd"] }
 arrow-ord = { workspace = true }
 arrow-schema = { workspace = true }
@@ -94,7 +95,8 @@ tokio = { workspace = true, features = [
     "parking_lot",
 ] }
 
-# Required for spill compression codec support (see comment on arrow-ipc dependency above).
+# `arrow-ipc` is used only through the `arrow::ipc` re-export, so cargo-machete
+# reports it as unused even though this crate relies on its codec features.
 [package.metadata.cargo-machete]
 ignored = ["arrow-ipc"]
 

datafusion/physical-plan/src/spill/mod.rs

@@ -298,8 +298,9 @@ impl IPCStreamWriter {
     /// those features are absent, `try_with_compression` will return an
     /// error at runtime for [`SpillCompression::Lz4Frame`] and
     /// [`SpillCompression::Zstd`] variants. The Cargo dependency keeps this
-    /// contract local and compiler-visible rather than relying solely on
-    /// workspace-level feature unification.
+    /// contract local and build-visible during Cargo feature resolution,
+    /// rather than relying solely on workspace-level feature unification;
+    /// see #21917.
     pub fn new(
         path: &Path,
         schema: &Schema,

datafusion/sqllogictest/Cargo.toml

@@ -94,7 +94,7 @@ harness = false
 name = "sqllogictests"
 path = "bin/sqllogictests.rs"
 
-# Required because we pull serde_json with a feature to get consistent pg display,
-# but its not directly used.
+# Opportunistic cargo-machete cleanup: serde_json is pulled with a feature to get
+# consistent pg display, but is not directly used in this crate.
 [package.metadata.cargo-machete]
 ignored = ["serde_json"]