document some rustc_dump attributes by mejrs · Pull Request #161556 · rust-lang/rust

mejrs · 2026-08-22T20:01:31Z

r? @fmease I think you're the most familiar with these at this time?

rustbot · 2026-08-22T20:01:35Z

Some changes occurred in compiler/rustc_attr_ir

fmease

I would've never thought of using #[doc(attribute(…))] within rustc itself, nice! ^^

Regarding the actual pieces of documentation you've added, I have to admit that I'm questioning their value in their current form. Let me elaborate:

The synopsis / first sentence is basically just restating the name in prose
The link to the corresponding AttributeKind shouldn't really be of any interest to the rustc dev looking into utilizing the internal attribute at hand
- in 99.9% of cases, they don't intend to modify/extend the attribute; in most cases they just want to use the attribute to dump info for tests or for debugging
- most of these AttributeKind are trivial/boring by being unit variants (and they would need to grep/jump-to-references separately anyway to find the actual impl)
- in the 0.01% of cases where they do plan to modify the attribute itself, they will know how to grep for the impl
The example code snippet is nice for skimming I suppose but the info where to place the attribute can be derived from taking a look at ALLOWED_TARGETS / by trial & error
The copy/pasted compiler output is valuable for understanding what sort of information the given attribute can provide
- however, it's bound to get out of date since it would need to be kept in sync manually, an impossible task
- today, this kind of information can be gathered by grepping tests/ui/ since there's guaranteed to be a corresponding test; and the nice part is: the "example output" is a *.stderr file which has to be up to date or else the test would fail!

I'm not saying that we shouldn't write documentation for these internal dumping attributes but I'd be a lot more interested in docs that would semi-thoroughly explain the important&interesting parts of the respective debug output if extant (also prone to becoming outdated like all documentation but not as prone as pasted compiler output if it "talks more general concepts" / provides good info beyond the basics).

Right now, we do have a table in the rustc dev guide that's frankly also rather terse: https://rustc-dev-guide.rust-lang.org/compiler-debugging.html#rustc_-test-attributes

I'm sorry if this sounds rather discouraging after you having done all that work!

View changes since this review

mejrs · 2026-08-22T22:07:57Z

I plan on documenting most (if not all) the interesting/useful/"spicy" attributes. This is just a start :) So keep "what would it look like if everything is documented" in mind.

The synopsis / first sentence is basically just restating the name in prose

They are what shows up in the module docs though, see below, and I dislike having gaps there:

2. The link to the corresponding AttributeKind shouldn't really be of any interest to the rustc dev looking into utilizing the internal attribute at hand

It is slightly annoying to figure out what the variant name is, though. Just searching https://doc.rust-lang.org/nightly/nightly-rustc/ and following links is easier than grepping, especially if you don't know what the precise name is. It has annoyed me in the past trying to look that up. And I think that if every attribute was documented like this, it would save me (and hopefully others) some bits of time here and there :)

3. The example code snippet is nice for skimming I suppose but the info where to place the attribute can be derived from taking a look at ALLOWED_TARGETS / by trial & error

Like the std attribute docs, I'm not aiming to be thorough and precise (at least not in the dump attributes case). These attributes are very useful for teaching Rust and discussing various rustc implementation details. So it is very nice to be able to able to quickly link to and copy paste from a place like this. This is also why I've written several unstable book entries.

The copy/pasted compiler output is valuable for understanding what sort of information the given attribute can provide

however, it's bound to get out of date since it would need to be kept in sync manually, an impossible task

today, this kind of information can be gathered by grepping tests/ui/ since there's guaranteed to be a corresponding test; and the nice part is: the "example output" is a *.stderr file which has to be up to date or else the test would fail!

It should be possible to turn these into ui tests and #[doc = include_str!(..)] them into the docs, right? I'm happy to do that if there's no issues with it.

fmease · 2026-08-22T22:44:57Z

@@ -0,0 +1,759 @@
+#[cfg_attr(not(bootstrap), doc(attribute = "rustc_dump_clauses"))]
+/// Dumps the clauses of the annotated item.


Below this, could you add a brief paragraph mentioning query clauses_of (and ty::Clause maybe in some way)? I know we can't intra-doc-link to them but still.

Why is mentioning clauses_of of importance? Well, it's important to know that it doesn't dump the result of query explicit_clauses_of or item_bounds for example. It's worth clarifying since synopsis "the clauses of the annotated item" is (rightly) rather vague unless you already know clauses_of.

Concretely, this actually "dumps a list of clauses that must be proven true at usage sites and which can be assumed at the definition site which consists of the explicit user-written clauses, the inferred outlives-clauses and clause <Self as Trait> if the item is a trait Trait".

I'm imagining the paragraph could be of the form "For more details, see query clauses_of and type ty::Clause." or preferably something akin to "This dumps the list of ty::Clauses as computed by query clauses_of."

View changes since the review

fmease · 2026-08-23T08:59:15Z

The copy/pasted compiler output is valuable for understanding what sort of information the given attribute can provide

however, it's bound to get out of date since it would need to be kept in sync manually, an impossible task

today, this kind of information can be gathered by grepping tests/ui/ since there's guaranteed to be a corresponding test; and the nice part is: the "example output" is a *.stderr file which has to be up to date or else the test would fail!

It should be possible to turn these into ui tests and #[doc = include_str!(..)] them into the docs, right? I'm happy to do that if there's no issues with it.

Yeah, let's go with that! :)

Something like the following should definitely work:

///
/// ```compile_fail
#[doc = include_str!("../../../tests/ui/<bikeshed>/<name>.rs")]
/// ```
///
/// ```text
#[doc = include_str!("../../../tests/ui/<bikeshed>/<name>.stderr")]
/// ```

mejrs · 2026-08-24T17:35:58Z

@fmease I think that's all the feedback taken care of. let me know what you think - I'm not sure what you've had in mind for some of them.

@rustbot ready

fmease · 2026-08-25T20:24:07Z

I would use the following normalization rule which is the most aggressive:

//@ normalize-stderr: "DefId\(.+?\)" -> "DefId(..)"

that should hopefully address the CI failure (admittedly, I've only skimmed the error log).

mejrs · 2026-08-25T20:45:31Z

I would use the following normalization rule which is the most aggressive:
//@ normalize-stderr: "DefId\(.+?\)" -> "DefId(..)"
that should hopefully address the CI failure (admittedly, I've only skimmed the error log).

it would (it's what i tried initially), but it turns DefId(0:4 ~ rustc_dump_generics[47be]::Struct::'lifetime), into DefId(..). Ideally I'd like to keep the path part of it around,

fmease

Thanks for applying all my feedback!

r=me with my two comments addressed in one way or another & maybe with commit "misc cleanups" and "normalize stuff" "squashed away".

View changes since this review

fmease · 2026-08-25T20:20:51Z

Could you remove the preexisting tests/ui/dump-clauses.rs? I originally added it when adding the attribute just so we have at least one place where we exercise the clause & item bounds attributes (since it was more meant for local debugging) ... but this file plus the other one for item bounds now serve this exact purpose.

fmease · 2026-08-30T14:10:39Z

+#[doc(attribute = "rustc_dump_inferred_outlives")]
+/// Dumps the inferred outlives-clauses of the annotated item.
+///
+/// See also the [`inferred_outlives_of`] query.


With "mention the corresponding/backing query (in a following paragraph)" in various review comments I was more thinking of a direct phrasing like

Suggested change

/// See also the [`inferred_outlives_of`] query.

/// They get computed by the [`inferred_outlives_of`] query.

but that's on me for being too vague.

"See also" is also fine, so feel free to ignore this.

mejrs · 2026-08-30T15:22:46Z

maybe with commit "misc cleanups" and "normalize stuff" "squashed away".

I will, I pushed feedback changes them as separate commits to make reviewing (and keeping track of) them easier.

rustbot · 2026-08-30T15:43:04Z

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

mejrs · 2026-08-31T09:39:18Z

@bors r=fmease

rust-bors · 2026-08-31T09:39:21Z

📌 Commit 52d85d7 has been approved by fmease

It is now in the queue for this repository.

rust-bors · 2026-08-31T11:08:11Z

⌛ Testing commit 52d85d7 with merge 2562a0f...

Workflow: https://github.com/rust-lang/rust/actions/runs/33385551665

@fmease

document some rustc_dump attributes r? @fmease I think you're the most familiar with these at this time?

@fmease

document some rustc_dump attributes r? @fmease I think you're the most familiar with these at this time?

Zalathar · 2026-08-31T11:21:45Z

@bors yield (enclosing rollup)

rust-bors · 2026-08-31T11:21:48Z

Auto build was cancelled. Cancelled workflows:

https://github.com/rust-lang/rust/actions/runs/33385551665

The next pull request likely to be tested is #162056.

Rollup of 5 pull requests Successful merges: - #161556 (document some rustc_dump attributes) - #161353 (Add test for parallel compiler reproducible build) - #161776 (Add a couple polonius tests and move universal region liveness generation) - #162002 (Output `tests/debuginfo` raw JSON data on failure in CI) - #162049 (Fix a compile error on the ESP-IDF target)

@fmease

document some rustc_dump attributes r? @fmease I think you're the most familiar with these at this time?

@fmease

document some rustc_dump attributes r? @fmease I think you're the most familiar with these at this time?

…uwer Rollup of 6 pull requests Successful merges: - #162058 (Port 1.98.1 release notes into main) - #161556 (document some rustc_dump attributes) - #161776 (Add a couple polonius tests and move universal region liveness generation) - #162002 (Output `tests/debuginfo` raw JSON data on failure in CI) - #162049 (Fix a compile error on the ESP-IDF target) - #162054 (Refine InferCtxtInner docs)

rustbot assigned fmease Aug 22, 2026

fmease reviewed Aug 22, 2026

View reviewed changes

fmease added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 22, 2026

mejrs force-pushed the attr_docs branch from 5ef928d to 6f8e9b3 Compare August 24, 2026 08:40

This comment has been minimized.

Sign in to view

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Aug 24, 2026

This comment has been minimized.

Sign in to view

mejrs force-pushed the attr_docs branch from 715395b to 73405f4 Compare August 26, 2026 09:44

fmease approved these changes Aug 30, 2026

View reviewed changes

fmease added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 30, 2026

mejrs force-pushed the attr_docs branch from 73405f4 to e89dc18 Compare August 30, 2026 15:43

mejrs added 2 commits August 30, 2026 17:43

document some rustc_dump attributes

b9fb957

remove redundant test

52d85d7

mejrs force-pushed the attr_docs branch from e89dc18 to 52d85d7 Compare August 30, 2026 15:51

rust-bors Bot 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-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Aug 31, 2026

rust-bors Bot pushed a commit that referenced this pull request Aug 31, 2026

Auto merge of #161556 - mejrs:attr_docs, r=fmease

2562a0f

document some rustc_dump attributes r? @fmease I think you're the most familiar with these at this time?

Zalathar added a commit to Zalathar/rust that referenced this pull request Aug 31, 2026

Rollup merge of rust-lang#161556 - mejrs:attr_docs, r=fmease

c48409c

document some rustc_dump attributes r? @fmease I think you're the most familiar with these at this time?

Zalathar mentioned this pull request Aug 31, 2026

Rollup of 5 pull requests #162056

Closed

JonathanBrouwer added a commit to JonathanBrouwer/rust that referenced this pull request Aug 31, 2026

Rollup merge of rust-lang#161556 - mejrs:attr_docs, r=fmease

f1a31a2

document some rustc_dump attributes r? @fmease I think you're the most familiar with these at this time?

JonathanBrouwer mentioned this pull request Aug 31, 2026

Rollup of 5 pull requests #162059

Closed

JonathanBrouwer added a commit to JonathanBrouwer/rust that referenced this pull request Aug 31, 2026

Rollup merge of rust-lang#161556 - mejrs:attr_docs, r=fmease

d7e2051

document some rustc_dump attributes r? @fmease I think you're the most familiar with these at this time?

JonathanBrouwer mentioned this pull request Aug 31, 2026

Rollup of 6 pull requests #162060

Open

		@@ -0,0 +1,759 @@
		#[cfg_attr(not(bootstrap), doc(attribute = "rustc_dump_clauses"))]
		/// Dumps the clauses of the annotated item.

	/// See also the [`inferred_outlives_of`] query.
	/// They get computed by the [`inferred_outlives_of`] query.

Uh oh!

Uh oh!

Conversation

mejrs commented Aug 22, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Aug 22, 2026

Uh oh!

fmease left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mejrs commented Aug 22, 2026

Uh oh!

fmease Aug 22, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fmease commented Aug 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

mejrs commented Aug 24, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

fmease commented Aug 25, 2026

Uh oh!

mejrs commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fmease left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fmease Aug 25, 2026

Choose a reason for hiding this comment

Uh oh!

fmease Aug 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mejrs commented Aug 30, 2026

Uh oh!

rustbot commented Aug 30, 2026

Uh oh!

mejrs commented Aug 31, 2026

Uh oh!

rust-bors Bot commented Aug 31, 2026

Uh oh!

rust-bors Bot commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Zalathar commented Aug 31, 2026

Uh oh!

rust-bors Bot commented Aug 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mejrs commented Aug 22, 2026 •

edited by rustbot

Loading

fmease left a comment •

edited

Loading

fmease Aug 22, 2026 •

edited by rustbot

Loading

fmease commented Aug 23, 2026 •

edited

Loading

mejrs commented Aug 25, 2026 •

edited

Loading

fmease left a comment •

edited

Loading

fmease Aug 30, 2026 •

edited

Loading

rust-bors Bot commented Aug 31, 2026 •

edited

Loading