Skip to content

Improve formatting of doc code blocks #144478

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 5 commits into from
Aug 3, 2025
Merged

Improve formatting of doc code blocks #144478

merged 5 commits into from
Aug 3, 2025

Conversation

joshtriplett
Copy link
Member

We don't currently apply automatic formatting to doc comment code blocks. As a
result, it has built up various idiosyncracies, which make such automatic
formatting difficult. Some of those idiosyncracies also make things harder for
human readers or other tools.

This PR makes a few improvements to doc code formatting, in the hopes of making
future automatic formatting easier, as well as in many cases providing net
readability improvements.

I would suggest reading each commit separately, as each commit contains one
class of changes.

@rustbot
Copy link
Collaborator

rustbot commented Jul 26, 2025

r? @ibraheemdev

rustbot has assigned @ibraheemdev.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

@rustbot rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Jul 26, 2025
@rust-log-analyzer

This comment has been minimized.

Sign in to view
@joshtriplett
Copy link
Member Author

This error didn't show up in local testing. Investigating.

@joshtriplett
Skip formatting for some compiler documentation code
3352dfc 
These examples feature Rust code that's presented primarily to
illustrate how its compilation would be handled, and these examples are
formatted to highlight those aspects in ways that rustfmt wouldn't
preserve. Turn formatting off in those examples.

(Doc code isn't formatted yet, but this will make it easier to enable
doc code formatting in the future.)
@joshtriplett
Improve and regularize comment placement in doc code
7150880 
Because doc code does not get automatically formatted, some doc code has
creative placements of comments that automatic formatting can't handle.
Reformat those comments to make the resulting code support standard Rust
formatting without breaking; this is generally an improvement to
readability as well.

Some comments are not indented to the prevailing indent, and are instead
aligned under some bit of code. Indent them to the prevailing indent,
and put spaces *inside* the comments to align them with code.

Some comments span several lines of code (which aren't the line the
comment is about) and expect alignment. Reformat them into one comment
not broken up by unrelated intervening code.

Some comments are placed on the same line as an opening brace, placing
them effectively inside the subsequent block, such that formatting would
typically format them like a line of that block. Move those comments to
attach them to what they apply to.

Some comments are placed on the same line as a one-line braced block,
effectively attaching them to the closing brace, even though they're
about the code inside the block. Reformat to make sure the comment will
stay on the same line as the code it's commenting.
@joshtriplett
Avoid placing // FIXME comments inside doc code blocks
b6c54a9 
This leads tools like rustfmt to get confused, because the doc code
block effectively spans two doc comments. As a result, the tools think
the first code block is unclosed, and the subsequent terminator opens a
new block.

Move the FIXME comments outside the doc code blocks, instead.
@joshtriplett
Add parentheses around expression arguments to ..
56c5b1d 
This makes it easier for humans to parse, and improves the result of
potential future automatic formatting.
@joshtriplett
Avoid making the start of a doc code block conditional
1e2d587 
Placing the opening triple-backquote inside a `cfg_attr` makes many
tools confused, including syntax highlighters (e.g. vim's) and rustfmt.

Instead, use a `cfg` inside the doc code block.
@joshtriplett joshtriplett force-pushed the doc-code-formatting-prep branch from 175fa91 to 1e2d587 Compare July 26, 2025 05:14
@Amanieu
Copy link
Member

Amanieu commented Aug 1, 2025

@bors r+ rollup

@bors
Copy link
Collaborator

bors commented Aug 1, 2025

📌 Commit 1e2d587 has been approved by Amanieu

It is now in the queue for this repository.

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 1, 2025
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this pull request Aug 1, 2025
@GuillaumeGomez
Rollup merge of rust-lang#144478 - joshtriplett:doc-code-formatting-p…
5532c3b 
…rep, r=Amanieu

Improve formatting of doc code blocks

We don't currently apply automatic formatting to doc comment code blocks. As a
result, it has built up various idiosyncracies, which make such automatic
formatting difficult. Some of those idiosyncracies also make things harder for
human readers or other tools.

This PR makes a few improvements to doc code formatting, in the hopes of making
future automatic formatting easier, as well as in many cases providing net
readability improvements.

I would suggest reading each commit separately, as each commit contains one
class of changes.
@GuillaumeGomez GuillaumeGomez mentioned this pull request Aug 1, 2025
Closed
bors added a commit that referenced this pull request Aug 1, 2025
@bors
Auto merge of #144791 - GuillaumeGomez:rollup-ujf9ae4, r=GuillaumeGomez
3d207da 
Rollup of 11 pull requests

Successful merges:

 - #132748 (get rid of some false negatives in rustdoc::broken_intra_doc_links)
 - #135771 ([rustdoc] Add support for associated items in "jump to def" feature)
 - #143360 (loop match: error on `#[const_continue]` outside `#[loop_match]`)
 - #143662 ([rustdoc] Display unsafe attrs with edition 2024 `unsafe()` wrappers.)
 - #143900 ([rustdoc] Correctly handle `should_panic` doctest attribute and fix `--no-run` test flag on the 2024 edition)
 - #144478 (Improve formatting of doc code blocks)
 - #144703 ([test][AIX] ignore extern_weak linkage test)
 - #144747 (compiletest: Improve diagnostics for line annotation mismatches 2)
 - #144756 (detect infinite recursion with tail calls in ctfe)
 - #144766 (Add human readable name "Cygwin")
 - #144782 (Properly pass path to staged `rustc` to `compiletest` self-tests)

r? `@ghost`
`@rustbot` modify labels: rollup
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this pull request Aug 1, 2025
@GuillaumeGomez
Rollup merge of rust-lang#144478 - joshtriplett:doc-code-formatting-p…
b401100 
…rep, r=Amanieu

Improve formatting of doc code blocks

We don't currently apply automatic formatting to doc comment code blocks. As a
result, it has built up various idiosyncracies, which make such automatic
formatting difficult. Some of those idiosyncracies also make things harder for
human readers or other tools.

This PR makes a few improvements to doc code formatting, in the hopes of making
future automatic formatting easier, as well as in many cases providing net
readability improvements.

I would suggest reading each commit separately, as each commit contains one
class of changes.
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this pull request Aug 1, 2025
@GuillaumeGomez
Rollup merge of rust-lang#144478 - joshtriplett:doc-code-formatting-p…
940b94a 
…rep, r=Amanieu

Improve formatting of doc code blocks

We don't currently apply automatic formatting to doc comment code blocks. As a
result, it has built up various idiosyncracies, which make such automatic
formatting difficult. Some of those idiosyncracies also make things harder for
human readers or other tools.

This PR makes a few improvements to doc code formatting, in the hopes of making
future automatic formatting easier, as well as in many cases providing net
readability improvements.

I would suggest reading each commit separately, as each commit contains one
class of changes.
@GuillaumeGomez GuillaumeGomez mentioned this pull request Aug 1, 2025
Closed
bors added a commit that referenced this pull request Aug 2, 2025
@bors
Auto merge of #144799 - GuillaumeGomez:rollup-uvbelp4, r=GuillaumeGomez
5738fde 
Rollup of 12 pull requests

Successful merges:

 - #132748 (get rid of some false negatives in rustdoc::broken_intra_doc_links)
 - #135771 ([rustdoc] Add support for associated items in "jump to def" feature)
 - #143360 (loop match: error on `#[const_continue]` outside `#[loop_match]`)
 - #143662 ([rustdoc] Display unsafe attrs with edition 2024 `unsafe()` wrappers.)
 - #144478 (Improve formatting of doc code blocks)
 - #144703 ([test][AIX] ignore extern_weak linkage test)
 - #144747 (compiletest: Improve diagnostics for line annotation mismatches 2)
 - #144766 (Add human readable name "Cygwin")
 - #144782 (Properly pass path to staged `rustc` to `compiletest` self-tests)
 - #144786 (Cleanup the definition of `group_type`)
 - #144796 (Add my previous commit name to .mailmap)
 - #144797 (Update safety comment for new_unchecked in niche_types)

r? `@ghost`
`@rustbot` modify labels: rollup
samueltardieu added a commit to samueltardieu/rust that referenced this pull request Aug 2, 2025
@samueltardieu
Rollup merge of rust-lang#144478 - joshtriplett:doc-code-formatting-p…
52407c7 
…rep, r=Amanieu

Improve formatting of doc code blocks

We don't currently apply automatic formatting to doc comment code blocks. As a
result, it has built up various idiosyncracies, which make such automatic
formatting difficult. Some of those idiosyncracies also make things harder for
human readers or other tools.

This PR makes a few improvements to doc code formatting, in the hopes of making
future automatic formatting easier, as well as in many cases providing net
readability improvements.

I would suggest reading each commit separately, as each commit contains one
class of changes.
@samueltardieu samueltardieu mentioned this pull request Aug 2, 2025
Closed
bors added a commit that referenced this pull request Aug 2, 2025
@bors
Auto merge of #144810 - samueltardieu:rollup-ytnjvge, r=samueltardieu
5a23cc7 
Rollup of 18 pull requests

Successful merges:

 - #132748 (get rid of some false negatives in rustdoc::broken_intra_doc_links)
 - #135771 ([rustdoc] Add support for associated items in "jump to def" feature)
 - #143360 (loop match: error on `#[const_continue]` outside `#[loop_match]`)
 - #143662 ([rustdoc] Display unsafe attrs with edition 2024 `unsafe()` wrappers.)
 - #143771 (Constify some more `Result` functions)
 - #143900 ([rustdoc] Correctly handle `should_panic` doctest attribute and fix `--no-run` test flag on the 2024 edition)
 - #144185 (Document guarantees of poisoning)
 - #144395 (update fortanix tests)
 - #144478 (Improve formatting of doc code blocks)
 - #144614 (Fortify RemoveUnneededDrops test.)
 - #144703 ([test][AIX] ignore extern_weak linkage test)
 - #144747 (compiletest: Improve diagnostics for line annotation mismatches 2)
 - #144756 (detect infinite recursion with tail calls in ctfe)
 - #144766 (Add human readable name "Cygwin")
 - #144782 (Properly pass path to staged `rustc` to `compiletest` self-tests)
 - #144786 (Cleanup the definition of `group_type`)
 - #144796 (Add my previous commit name to .mailmap)
 - #144797 (Update safety comment for new_unchecked in niche_types)

Failed merges:

 - #144805 (compiletest: Preliminary cleanup of `ProcRes` printing/unwinding)

r? `@ghost`
`@rustbot` modify labels: rollup
@samueltardieu samueltardieu mentioned this pull request Aug 2, 2025
Merged
bors added a commit that referenced this pull request Aug 2, 2025
@bors
Auto merge of #144814 - samueltardieu:rollup-qyum1hj, r=samueltardieu
5b9564a 
Rollup of 17 pull requests

Successful merges:

 - #132748 (get rid of some false negatives in rustdoc::broken_intra_doc_links)
 - #143360 (loop match: error on `#[const_continue]` outside `#[loop_match]`)
 - #143662 ([rustdoc] Display unsafe attrs with edition 2024 `unsafe()` wrappers.)
 - #143771 (Constify some more `Result` functions)
 - #144185 (Document guarantees of poisoning)
 - #144395 (update fortanix tests)
 - #144478 (Improve formatting of doc code blocks)
 - #144614 (Fortify RemoveUnneededDrops test.)
 - #144703 ([test][AIX] ignore extern_weak linkage test)
 - #144747 (compiletest: Improve diagnostics for line annotation mismatches 2)
 - #144756 (detect infinite recursion with tail calls in ctfe)
 - #144766 (Add human readable name "Cygwin")
 - #144782 (Properly pass path to staged `rustc` to `compiletest` self-tests)
 - #144786 (Cleanup the definition of `group_type`)
 - #144796 (Add my previous commit name to .mailmap)
 - #144797 (Update safety comment for new_unchecked in niche_types)
 - #144803 (rustc-dev-guide subtree update)

r? `@ghost`
`@rustbot` modify labels: rollup
@bors bors merged commit d082ff4 into rust-lang:master Aug 3, 2025
10 checks passed
@rustbot rustbot added this to the 1.90.0 milestone Aug 3, 2025
rust-timer added a commit that referenced this pull request Aug 3, 2025
@rust-timer
Unrolled build for #144478
efda657 
Rollup merge of #144478 - joshtriplett:doc-code-formatting-prep, r=Amanieu

Improve formatting of doc code blocks

We don't currently apply automatic formatting to doc comment code blocks. As a
result, it has built up various idiosyncracies, which make such automatic
formatting difficult. Some of those idiosyncracies also make things harder for
human readers or other tools.

This PR makes a few improvements to doc code formatting, in the hopes of making
future automatic formatting easier, as well as in many cases providing net
readability improvements.

I would suggest reading each commit separately, as each commit contains one
class of changes.
github-actions bot pushed a commit to rust-lang/rustc-dev-guide that referenced this pull request Aug 4, 2025
@bors
Auto merge of #144814 - samueltardieu:rollup-qyum1hj, r=samueltardieu
bcf22c4 
Rollup of 17 pull requests

Successful merges:

 - rust-lang/rust#132748 (get rid of some false negatives in rustdoc::broken_intra_doc_links)
 - rust-lang/rust#143360 (loop match: error on `#[const_continue]` outside `#[loop_match]`)
 - rust-lang/rust#143662 ([rustdoc] Display unsafe attrs with edition 2024 `unsafe()` wrappers.)
 - rust-lang/rust#143771 (Constify some more `Result` functions)
 - rust-lang/rust#144185 (Document guarantees of poisoning)
 - rust-lang/rust#144395 (update fortanix tests)
 - rust-lang/rust#144478 (Improve formatting of doc code blocks)
 - rust-lang/rust#144614 (Fortify RemoveUnneededDrops test.)
 - rust-lang/rust#144703 ([test][AIX] ignore extern_weak linkage test)
 - rust-lang/rust#144747 (compiletest: Improve diagnostics for line annotation mismatches 2)
 - rust-lang/rust#144756 (detect infinite recursion with tail calls in ctfe)
 - rust-lang/rust#144766 (Add human readable name "Cygwin")
 - rust-lang/rust#144782 (Properly pass path to staged `rustc` to `compiletest` self-tests)
 - rust-lang/rust#144786 (Cleanup the definition of `group_type`)
 - rust-lang/rust#144796 (Add my previous commit name to .mailmap)
 - rust-lang/rust#144797 (Update safety comment for new_unchecked in niche_types)
 - rust-lang/rust#144803 (rustc-dev-guide subtree update)

r? `@ghost`
`@rustbot` modify labels: rollup
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees

@ibraheemdev ibraheemdev

Labels
S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. T-libs Relevant to the library team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
1.90.0
Development

Successfully merging this pull request may close these issues.
6 participants
@joshtriplett @rustbot @rust-log-analyzer @Amanieu @bors @ibraheemdev