rustdoc: show inner enum and struct in type definition for concrete type

[Urgau]

This PR implements the Display enum variants for generic enum in type def page #rustdoc/zulip proposal.

This proposal comes from looking at TyKind typedef from the compiler. On that page, the documentation is able to show the layout for each variant, but not the variants themselves. This proposal suggests showing the fields and variants for those "concrete type". This would mean that instead of having many unresolved generics, like in IrTyKind:

    Array(I::Ty, I::Const),
    Slice(I::Ty),
    RawPtr(I::TypeAndMut),
    Ref(I::Region, I::Ty, I::Mutability),
    FnDef(I::DefId, I::GenericArgsRef),

those would be resolved with direct links to the proper types in the TyKind typedef page:

    Array(Ty<'tcx>, Const<'tcx>),
    Slice(Ty<'tcx>),
    RawPtr(TypeAndMut<'tcx>),
    Ref(Region<'tcx>, Ty<'tcx>, Mutability<'tcx>),
    FnDef(DefId<'tcx>, GenericArgsRef<'tcx>),

Saving both time and confusion.

---

Old description

I've chosen to add the enums and structs under the "Show Aliased Type" details, as well as showing the variants and fields under the usual "Variants" and "Fields" sections. under new the Inner Variants and Inner Fields sections (except for their names, they are identical to the one found in the enum, struct and union pages). Those sections are complementary and do not replace anything else.

This PR proposes the following condition for showing the aliased type (basically, has the aliased type some generics that are all of them resolved):

• the typedef does NOT have any generics (modulo lifetimes)
• AND the aliased type has some generics

Examples

pub enum IrTyKind<'a, I: Interner> {
    /// Doc comment for AdtKind
    AdtKind(&'a I::Adt),
    /// and another one for TyKind
    TyKind(I::Adt, I::Ty),
    // no comment
    StructKind { a: I::Adt, },
}

pub type TyKind<'a> = IrTyKind<'a, TyCtxt>;

Old

pub struct One<T> {
    pub val: T,
    #[doc(hidden)]
    pub inner_tag: u64,
    __hidden: T,
}

/// `One` with `u64` as payload
pub type OneU64 = One<u64>;

Old

r? @GuillaumeGomez

[rustbot]

Some changes occurred in src/librustdoc/clean/types.rs

cc @camelid

[GuillaumeGomez]

Just having "inner fields" isn't great. Maybe we could show the aliased type definition in a "show aliased type" thing like we have for "show all" when there are too any fields/variants?

[rustbot]

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez, @Folyd, @jsha

[Urgau]

Sure. I've pushed a commit that does this. (I'm not sure about the CSS changes, I would appreciate some guidance).

Closed:

Opened:

EDIT: This layout is out of date. Please refer to the description for up to date ones.

[Urgau]

I've discussed with @GuillaumeGomez on Zulip about the UI layout and we concluded that it should also display the enum/struct code definition. So I've added it.

[GuillaumeGomez]

Looks really nice! I'm a big fan of this change considering how often we encounter it in rustc's docs. Once we're done with this review round, I'll start an FCP as it is a UI change.

[fmease]

Some small style suggestions. I haven't looked at the changes from a semantic standpoint yet, I'm gonna do so earliest tomorrow.

Edit: Thanks a lot for working on this, this will help tremendously when browsing the rustc docs!

[bors]

☔ The latest upstream changes (presumably #114905) made this pull request unmergeable. Please resolve the merge conflicts.

[fmease]

Have you checked if it handles #[doc(hidden)] correctly (with and without --document-hidden-items -Zunstable-options)? On fields and on variants?

Edit: I've just checked myself, it doesn't.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[GuillaumeGomez]

Thanks everyone!

@bors r+

[bors]

📌 Commit 85e4b89 has been approved by GuillaumeGomez

It is now in the queue for this repository.

[bors]

⌛ Testing commit 85e4b89 with merge 70c7e4d...

[bors]

☀️ Test successful - checks-actions
Approved by: GuillaumeGomez
Pushing 70c7e4d to master...

[rust-timer]

Finished benchmarking commit (70c7e4d): comparison URL.

Overall result: ❌ regressions - no action needed

@rustbot label: -perf-regression

Instruction count

This is a highly reliable metric that was used to determine the overall result at the top of this comment.

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

Max RSS (memory usage)

Results

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

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

Cycles

This benchmark run did not return any relevant results for this metric.

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 629.026s -> 628.819s (-0.03%)
Artifact size: 318.02 MiB -> 318.09 MiB (0.02%)

[notriddle]

Of course there's a regression. It's emitting more HTML.

[jplatte]

Wow, this is amazing! Thanks to everybody involved in landing this 🤩
_{Could it be extended to also show applicable methods on type aliases? 🙏🏼}

[Urgau]

_{Could it be extended to also show applicable methods on type aliases? 🙏🏼}

Currently working on it! 😄

[GuillaumeGomez]

There was #112429 which we needed to revert. But luckily we now have #115201 which should be merged soon.