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.

[Jefffrey]

Have we decided to require nightly now for this updated CI check? Just wanna see if we need to get more visibility on this if so

[alamb]

I think we can either require nightly or just wait for the relevant feature to make it to stable

It is a good call to be potentially worried about the impact this change might have on developer flow (especially if nightly changes fmt a bunch...)

[Jefffrey]

I've posted on the mailing list and discord to get some visibility on this:

• https://lists.apache.org/thread/79cksvqqv5xpnolvwwon0kl88w61vvnz

Can probably wait a bit to get some opinions in. Alternatively we can omit the CI change for now and just have the formatting changes, and tackle the CI change later.

[CuteChuanChuan]

@Jefffrey
Thanks! No matter the final decision on CI change, this has been a very precious learning opportunity. Also sincerely appreciate @alamb 's valuable comment and encouragement.

[alamb]

Thanks @Jefffrey and @CuteChuanChuan

The other thing we could potentially do is keep this PR in reserve and wait for the doc formatting feature to become stable 🤔

The more I have thought about this the more I can see why it would be wise not to require nightly for our development flow.

On one hand, I suspect most people will still be able to run cargo fmt with the stable version of rust and it will be fine (as they won't be adding examples). However, I do think it will be annoying for people who add new examples, which maybe we don't want to discentivize

But I am still torn.