rustdoc: Improve `ItemKind` by fmease · Pull Request #162916 · rust-lang/rust

fmease · 2026-09-17T17:29:29Z

Fixes the absolutely hideous & messy ItemKind representations for associated items:

Consolidates RequiredAssocConstItem, ProvidedAssocConstItem & ImplAssocConstItem into new single AssocConst
Consolidates RequiredMethodItem & MethodItem into new single AssocFn
Consolidates RequiredAssocTypeItem & AssocTypeItem into new single AssocTy

Note that I'm responsible for some of these: In PR #95316 from 2022 I introduced TyAssocTypeItem (RequiredAssocTypeItem on main) & TyAssocConstItem (RequiredAssocConstItem on main) because I wanted to be consistent with the preexisting TyMethod <-> Method split.

The latter is far more egregious because it unnecessarily leaks into user-observable parts of the generated docs (search filter tymethod, URL fragment tymethod.f.html) (to be fixed at some point). Thankfully in said PR we changed the approach and didn't make the split user-observable for assoc consts & types.

As the reviewer of PR #134321 I'm also responsible for the ProvidedAssocConstItem <-> ImplAssocConstItem split which I deemed acceptable as a temporary solution.

Addresses #112901 (comment) & thereby fixes #112901.

_{(No LLM was or will be used by me during the entire creation process of this PR)}

fmease · 2026-09-17T17:29:49Z

@bors try @rust-timer queue

[WIP] rustdoc: Improve `ItemKind`

rust-bors · 2026-09-17T18:29:27Z

☀️ Try build successful (CI)
Build commit: 77d2154 (77d215460b0d48a45bad88d416cbd1326a27a011)
Base parent: c999cef (c999cef531ea9059e189e82fe0e82c5daf249bc9)

rust-timer · 2026-09-17T19:19:40Z

Finished benchmarking commit (77d2154): comparison URL.

Overall result: ❌✅ regressions and improvements - please read:

Benchmarking means the PR may be perf-sensitive. It's automatically marked not fit for rolling up. Overriding is possible but disadvised: it risks changing compiler perf.

Next, please: If you can, justify the regressions found in this try perf run in writing along with @rustbot label: +perf-regression-triaged. If not, fix the regressions and do another perf run. Neutral or positive results will clear the label automatically.

@bors rollup=never rustc-perf
@rustbot label: -S-waiting-on-perf +perf-regression

Instruction count

Our most reliable metric. Used to determine the overall result above. However, even this metric can be noisy.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	0.5%	[0.5%, 0.5%]	1
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-0.3%	[-0.4%, -0.1%]	8
All ❌✅ (primary)	-	-	0

Max RSS (memory usage)

Results (primary -0.8%, secondary 1.0%)

A less reliable metric. May be of interest, but not used to determine the overall result above.

	mean	range	count
Regressions ❌ (primary)	1.8%	[1.4%, 2.1%]	2
Regressions ❌ (secondary)	3.2%	[2.2%, 3.7%]	3
Improvements ✅ (primary)	-2.4%	[-3.1%, -2.0%]	3
Improvements ✅ (secondary)	-2.2%	[-2.7%, -1.6%]	2
All ❌✅ (primary)	-0.8%	[-3.1%, 2.1%]	5

Cycles

Results (secondary 1.6%)

A less reliable metric. May be of interest, but not used to determine the overall result above.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	3.7%	[3.3%, 4.2%]	2
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-2.7%	[-2.7%, -2.7%]	1
All ❌✅ (primary)	-	-	0

Binary size

This perf run didn't have relevant results for this metric.

Bootstrap: 500.132s -> 501.928s (0.36%)
Artifact size: 406.81 MiB -> 407.66 MiB (0.21%)

fmease · 2026-09-23T12:27:15Z

@bors try @rust-timer queue

[WIP] rustdoc: Improve `ItemKind`

rust-bors · 2026-09-23T13:31:55Z

☀️ Try build successful (CI)
Build commit: cd705f8 (cd705f86135b1fb7806329fa0703adee0ced7717)
Base parent: 52d0fd8 (52d0fd8771cf35f8fdb31a41a96d545cebb74931)

rust-timer · 2026-09-23T14:56:02Z

Finished benchmarking commit (cd705f8): comparison URL.

Overall result: ❌✅ regressions and improvements - please read:

Benchmarking means the PR may be perf-sensitive. It's automatically marked not fit for rolling up. Overriding is possible but disadvised: it risks changing compiler perf.

Next, please: If you can, justify the regressions found in this try perf run in writing along with @rustbot label: +perf-regression-triaged. If not, fix the regressions and do another perf run. Neutral or positive results will clear the label automatically.

@bors rollup=never rustc-perf
@rustbot label: -S-waiting-on-perf +perf-regression

Instruction count

Our most reliable metric. Used to determine the overall result above. However, even this metric can be noisy.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	0.5%	[0.5%, 0.5%]	1
Improvements ✅ (primary)	-2.3%	[-3.8%, -0.2%]	3
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	-2.3%	[-3.8%, -0.2%]	3

Max RSS (memory usage)

Results (primary -1.9%)

A less reliable metric. May be of interest, but not used to determine the overall result above.

	mean	range	count
Regressions ❌ (primary)	1.1%	[1.1%, 1.1%]	1
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-2.9%	[-3.4%, -2.6%]	3
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	-1.9%	[-3.4%, 1.1%]	4

Cycles

Results (primary -3.0%)

A less reliable metric. May be of interest, but not used to determine the overall result above.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-3.0%	[-3.0%, -3.0%]	1
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	-3.0%	[-3.0%, -3.0%]	1

Binary size

This perf run didn't have relevant results for this metric.

Bootstrap: 494.96s -> 488.165s (-1.37%)
Artifact size: 406.90 MiB -> 407.05 MiB (0.04%)

rustbot · 2026-09-24T07:25:09Z

r? @lolbinarycat

rustbot has assigned @lolbinarycat.
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

Why was this reviewer chosen?

The reviewer was selected based on:

Owners of files modified in this PR: rustdoc
rustdoc expanded to 8 candidates
Random selection from GuillaumeGomez, lolbinarycat, notriddle

This prepares for the removal of their common suffix `Item`. It makes it trivial to mechanically mass rename them later, glob imports would render the endeavor a lot more brittle. The convention to go out of one's way to avoid enum namespacing (i.e., suffixing or prefixing the variants & glob importing them everywhere) is incredibly dated. It pollutes the module scope, it's annoying since one has to remember to add (here) suffix `Item` to new variants & referencing the variant names requires more to type compared to a function-local (here) `use clean::ItemKind::*;` for a `match` for example (although in most cases we won't glob import anyway, so that point isn't super relevant).

rustbot · 2026-10-08T11:31:38Z

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.

Moreover, rename `Function` to `Fn`, `ForeignFunction` to `ForeignFn`, `*Method` to `*AssocFn`, `*Type` to `*Ty`, `Constant` to `Const` & `Macro` to `DeclMacro`. Re. `Method`: In Rust, the term "method" specificially refers to associated functions that have a receiver / `self` parameter but this variant represents associated functions in general. Re. `Function` -> `Fn`: Since I don't want to name the "associated" variant `AssocFunction` (too lengthy) but `AssocFn`, so I'm changing the free variant, too, to have a more consistent naming scheme. `Macro` -> `DeclMacro`: To differentiate it from `ProcMacro`.

…ssocConst` I had to modify several HTML rendering routines because parameter `parent: ItemType` of fn `render_assoc_item` didn't always refer to the parent container (impl vs trait) since it was actually misused to control the styling (!), namely the indentation & the look of the where-clause, but now with `ProvidedAssocConst` & `ImplAssocConst` merged I needed to know the actual container to determine `AssocConstValue`. `render_assoc_item` previously only used the `parent` param to determine the indentation & `assoc_method` used it to determine the indentation & the style of the where-clause (see enum `Ending`; complete misnomer!). That led to `item_trait` (for rendering trait pages) literally passing `ItemType::Impl` for the "docs section" (as contrasted with the "code block") to avoid indenting it. To untangle this, I forced the callers of `render_assoc_item` to specify the indentation & the where-clause styling via new parameters. *Moreover*, as alluded to above, only `assoc_method` made the where-clause styling (`Ending`) dependent on the context, not however `assoc_const` or `assoc_ty`! I've fixed that here to avoid making the parameter list of `render_assoc_item` even longer & since it makes them consistent (thereby fixing the remaining issues reported in RUST-112901).

lolbinarycat

did line-by-line review of everything except the tests and rustdoc-json stuff. big fan of the changes so far! i always thought that enum was a bit of a mess, and this is a huge step towards cleaning it up (the main thing that's still a bit messy is DeclMacro vs ProcMacro, but that can be addressed in a followup).

will review the rest later, but for now, here's my comments.

View changes since this review

lolbinarycat · 2026-10-08T15:12:18Z

+    ProcMacro(ProcMacro),
+    Primitive(PrimitiveType),
+    Const(Box<Constant>),
+    AssocConst(Box<AssocConst>),


Do we want the inner type to always have the same name as the enum variant, for consistancy? Function is a reasonable exception b/c of the Fn trait, but there's no reason this shouldn't be Primative, Const, and DeclMacro, right?

lolbinarycat · 2026-10-08T15:24:58Z

+    AssocFnWithoutBody = 12,
+    AssocFnWithBody = 13,


Suggested change

AssocFnWithoutBody = 12,

AssocFnWithBody = 13,

AssocFnWithoutBody = 12, // "tymethod" in urls

AssocFnWithBody = 13, // "method" in urls

lolbinarycat · 2026-10-08T15:31:28Z

        let kind = match &self.kind {
-            ItemKind::StrippedItem(k) => k,
+            ItemKind::Stripped(k) => k,
            _ => &self.kind,
        };


this exact logic, either in the form of a match or if let, comes up enough that it might be worth factoring out into a utility method. not sure about the name, unstripped_kind maybe?

lolbinarycat · 2026-10-08T15:43:12Z

+        | ItemKind::AssocTy(clean::AssocTy { ty: Some(_), .. })
            if cache.parent_stack.last().is_some_and(|parent| parent.is_trait_impl()) =>
        {
            // skip associated items in trait impls


Suggested change

// skip associated items in trait impls

// skip associated items (besides methods) in trait impls

unrelated to the refactor, but this behavior is a bit arbitrary, it means std::collections::btree_map::IterMut::next shows up in search results but std::collections::btree_map::IterMut::Item doesn't

lolbinarycat · 2026-10-08T15:49:47Z

-    pub(crate) type_: Type,
+pub(crate) struct TyAlias {
    pub(crate) generics: Generics,
+    pub(crate) ty: Type,


assuming the value of the new field ty is equivalent to self.item_type.unwrap_or(self.type_), correct?

lolbinarycat · 2026-10-08T16:23:41Z

@@ -772,16 +766,7 @@ impl Item {

    /// Returns true if this a macro declared with the `macro` keyword or with `macro_rules!.


Suggested change

/// Returns true if this a macro declared with the `macro` keyword or with `macro_rules!.

/// Returns true if this a macro declared with the `macro` keyword or with `macro_rules!`, unless

/// it was defined with only `derive()` branches or only `attr()` branches.

lolbinarycat · 2026-10-08T16:29:34Z

 pub(crate) struct Function {
+    pub(crate) generics: Generics,
    pub(crate) decl: FnDecl,
+}


did you swap the order of these fields? it's hard to tell because the diff is very confused here.

lolbinarycat · 2026-10-08T16:40:22Z

        let kind = match &item.kind {
-            clean::StrippedItem(item) => item,
+            ItemKind::Stripped(item) => item,
            kind => kind,


another instance of this common pattern that could be factored out

lolbinarycat · 2026-10-08T16:54:01Z

    Ok(())
 }

 fn should_render_item(


Suggested change

fn should_render_item_in_deref_methods(

old name made this function sound way more general than it actually is.

lolbinarycat · 2026-10-08T16:59:06Z

+    let req_assoc_fns = filter_items(&t.items, |m| m.is_assoc_fn_without_body(), "tymethod");
+    let prov_assoc_fns = filter_items(&t.items, |m| m.is_assoc_fn_with_body(), "method");


I think these should still have method in the name, as traits can't have non-method functions and I don't believe there are currently any plans to change that.

This comment has been minimized.

Sign in to view

rustbot added the S-waiting-on-perf Status: Waiting on a perf run to be completed. label Sep 17, 2026

This comment has been minimized.

Sign in to view

rust-bors Bot pushed a commit that referenced this pull request Sep 17, 2026

Auto merge of #162916 - fmease:rustdoc-better-item-kinds, r=<try>

77d2154

[WIP] rustdoc: Improve `ItemKind`

fmease force-pushed the rustdoc-better-item-kinds branch from 75c7db0 to b15adfe Compare September 17, 2026 17:36

This comment has been minimized.

Sign in to view

rustbot added perf-regression Performance regression. and removed S-waiting-on-perf Status: Waiting on a perf run to be completed. labels Sep 17, 2026

This comment has been minimized.

Sign in to view

fmease force-pushed the rustdoc-better-item-kinds branch 3 times, most recently from 0da05b0 to 9cf241e Compare September 23, 2026 11:29

fmease added the C-cleanup Category: PRs that clean code up or issues documenting cleanup. label Sep 23, 2026

fmease force-pushed the rustdoc-better-item-kinds branch from 9cf241e to 628da35 Compare September 23, 2026 12:26

This comment has been minimized.

Sign in to view

rustbot added the S-waiting-on-perf Status: Waiting on a perf run to be completed. label Sep 23, 2026

This comment has been minimized.

Sign in to view

rust-bors Bot pushed a commit that referenced this pull request Sep 23, 2026

Auto merge of #162916 - fmease:rustdoc-better-item-kinds, r=<try>

cd705f8

[WIP] rustdoc: Improve `ItemKind`

fmease force-pushed the rustdoc-better-item-kinds branch from 628da35 to 9502ff1 Compare September 23, 2026 13:18

This comment has been minimized.

Sign in to view

rustbot removed the S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. label Sep 24, 2026

rustbot assigned lolbinarycat Sep 24, 2026

fmease mentioned this pull request Sep 24, 2026

rustdoc: Avoid re-HIR-ty-lowering tys & const args where possible #163217

Draft

This comment has been minimized.

Sign in to view

fmease force-pushed the rustdoc-better-item-kinds branch from f11bbf4 to f5b1c33 Compare September 25, 2026 20:17

This comment has been minimized.

Sign in to view

fmease force-pushed the rustdoc-better-item-kinds branch from f5b1c33 to 04fa31d Compare October 1, 2026 13:43

This comment has been minimized.

Sign in to view

fmease force-pushed the rustdoc-better-item-kinds branch from 04fa31d to 2173417 Compare October 2, 2026 15:46

This comment has been minimized.

Sign in to view

fmease force-pushed the rustdoc-better-item-kinds branch from 2173417 to c4269d7 Compare October 8, 2026 11:31

fmease force-pushed the rustdoc-better-item-kinds branch from c4269d7 to 588b522 Compare October 8, 2026 11:35

This comment has been minimized.

Sign in to view

fmease force-pushed the rustdoc-better-item-kinds branch from 588b522 to cbb4616 Compare October 8, 2026 11:50

fmease added 6 commits October 8, 2026 13:51

rustdoc: Consolidate RequiredAssocConst & AssocConst

ea2ed91

rustdoc: Remove unnecessary abstraction AssocConstValue

6e4abe0

rustdoc: Collapse TyAssocFn & AssocFn

ef4125d

rustdoc: Collapse RequiredAssocTy & AssocTy

db1912a

This comment has been minimized.

Sign in to view

fmease force-pushed the rustdoc-better-item-kinds branch from cbb4616 to a87ac7e Compare October 8, 2026 13:11

rustdoc: Reduce rightward drift in render_impl

a87ac7e

lolbinarycat reviewed Oct 8, 2026

View reviewed changes

	// skip associated items in trait impls
	// skip associated items (besides methods) in trait impls

		@@ -772,16 +766,7 @@ impl Item {

		/// Returns true if this a macro declared with the `macro` keyword or with `macro_rules!.

	/// Returns true if this a macro declared with the `macro` keyword or with `macro_rules!.
	/// Returns true if this a macro declared with the `macro` keyword or with `macro_rules!`, unless
	/// it was defined with only `derive()` branches or only `attr()` branches.

		let req_assoc_fns = filter_items(&t.items, \|m\| m.is_assoc_fn_without_body(), "tymethod");
		let prov_assoc_fns = filter_items(&t.items, \|m\| m.is_assoc_fn_with_body(), "method");

Conversation

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

Uh oh!

Uh oh!

fmease commented Sep 17, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

rust-bors Bot commented Sep 17, 2026

Uh oh!

This comment has been minimized.

rust-timer commented Sep 17, 2026

Overall result: ❌✅ regressions and improvements - please read:

Uh oh!

This comment has been minimized.

fmease commented Sep 23, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

rust-bors Bot commented Sep 23, 2026

Uh oh!

This comment has been minimized.

rust-timer commented Sep 23, 2026

Overall result: ❌✅ regressions and improvements - please read:

Uh oh!

rustbot commented Sep 24, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

rustbot commented Oct 8, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

lolbinarycat left a comment • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

fmease commented Sep 17, 2026 •

edited

Loading

lolbinarycat left a comment •

edited by rustbot

Loading