ci: add check for doc comment formatting

[CuteChuanChuan]

Which issue does this PR close?

• Closes Chore: format documentation examples #16915.
• Closes We have now the CI ensure all doc strings remain formatted #16916

Rationale for this change

This PR adds CI enforcement to ensure all code examples in documentation comments are properly formatted to maintain consistent code formatting, including examples in doc comments.

What changes are included in this PR?

This PR adds a new CI check in the check-fmt job that:

1. Installs the nightly Rust toolchain
2. Runs cargo +nightly fmt --all -- --check --config format_code_in_doc_comments=true

Note: format_code_in_doc_comments is currently an unstable feature.

Are these changes tested?

The command is tested locally with:

Are there any user-facing changes?

No user-facing changes.

[CuteChuanChuan]

Hi @alamb ,

Following the discussion in PR #16916, I've prepared this PR to enable CI enforcement for doc comment formatting.

As you mentioned, we need to use the same version of cargo fmt to avoid conflicts. Since
format_code_in_doc_comments is only available in nightly, this PR uses cargo +nightly fmt consistently in CI.

This PR contains two commits:

1. CI change: Install nightly toolchain and use cargo +nightly fmt --all -- --check --config format_code_in_doc_comments=true
2. Format fixes: Apply nightly rustfmt formatting to all existing doc comment code
   examples

PTAL when you have chance. Thank you!

[alamb]

Thanks @CuteChuanChuan -- this looks really close. I think we just need to update where the command is run and this will be good to go from my perspective

Thank you for sticking with it

[CuteChuanChuan]

Hi @alamb ,

Sorry for the late response. I've moved the nightly fmt command to ci/scripts/rust_fmt.sh as suggested.
PTAL when you have chances, thanks!

[CuteChuanChuan]

Hi @alamb , friendly ping on this when you have a moment. No rush! ♥️

[alamb]

Thank you @CuteChuanChuan -- this make sense to me ❤️

[alamb]

I merged up from main and ran cargo fmt again. Thank you for this @CuteChuanChuan -- it is a nice improvement.

The only final thing I am worried about is the developer experience here -- specifically helping developers know how to fix the errors when they encounter them

Specifically, running the script only generates the error

$ ci/scripts/rust_fmt.sh
+ rustup toolchain install nightly --component rustfmt
info: syncing channel updates for 'nightly-aarch64-apple-darwin'
info: latest update on 2026-01-01, rust version 1.94.0-nightly (8d670b93d 2025-12-31)
info: component 'rustfmt' for target 'aarch64-apple-darwin' is up to date

  nightly-aarch64-apple-darwin unchanged - rustc 1.94.0-nightly (8d670b93d 2025-12-31)

info: checking for self-update
+ cargo +nightly fmt --all -- --check --config format_code_in_doc_comments=true
Diff in /Users/andrewlamb/Software/datafusion2/datafusion/core/src/physical_planner.rs:1906:
 /// splitting AND conjunctions into individual expressions.
 /// Column qualifiers are stripped so expressions can be evaluated against
 /// the TableProvider's schema.
-///
 fn extract_dml_filters(input: &Arc<LogicalPlan>) -> Result<Vec<Expr>> {
     let mut filters = Vec::new();

Diff in /Users/andrewlamb/Software/datafusion2/datafusion/core/src/physical_planner.rs:1944:
 /// For UPDATE statements, the SQL planner encodes assignments as a projection
 /// over the source table. This function extracts column name and expression pairs
 /// from the projection. Column qualifiers are stripped from the expressions.
-///
 fn extract_update_assignments(input: &Arc<LogicalPlan>) -> Result<Vec<(String, Expr)>> {
     // The UPDATE input plan structure is:
     // Projection(updated columns as expressions with aliases)

I had to go digging into script to find out how to actually fix thins:

cargo +nightly fmt --all -- --config format_code_in_doc_comments=true

Maybe we can also add a comment (or an error message) that tells people how to fix this error if they encouter it

[CuteChuanChuan]

@alamb,
thanks for pointing this out. I think adding a comment/error msg is quite beneficial. Let me improve this.