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

Urgau · 2023-08-15T13:45:01Z

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 · 2023-08-15T13:45:08Z

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

cc @camelid

GuillaumeGomez · 2023-08-15T13:51:28Z

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 · 2023-08-16T09:04:47Z

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez, @Folyd, @jsha

Urgau · 2023-08-16T09:05:09Z

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 · 2023-08-16T11:04:47Z

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.

src/librustdoc/clean/mod.rs

src/librustdoc/clean/types.rs

src/librustdoc/html/render/print_item.rs

GuillaumeGomez · 2023-08-16T12:16:21Z

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!

src/librustdoc/clean/types.rs

src/librustdoc/html/render/print_item.rs

bors · 2023-08-16T22:31:12Z

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

src/librustdoc/clean/mod.rs

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.

src/librustdoc/clean/mod.rs

rfcbot · 2023-08-28T15:55:29Z

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

rfcbot · 2023-09-07T15:55:51Z

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 · 2023-09-07T15:58:35Z

Thanks everyone!

@bors r+

bors · 2023-09-07T15:58:37Z

📌 Commit 85e4b89 has been approved by GuillaumeGomez

It is now in the queue for this repository.

bors · 2023-09-07T16:23:06Z

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

bors · 2023-09-07T18:07:27Z

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

rust-timer · 2023-09-07T19:41:01Z

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 · 2023-09-07T20:56:46Z

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

jplatte · 2023-09-08T11:37:35Z

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

Urgau · 2023-09-08T11:39:13Z

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

Currently working on it! 😄

GuillaumeGomez · 2023-09-08T11:47:57Z

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

Pkgsrc changes: * Remove NetBSD-8 support (embedded LLVm requires newer C++ than what is in -8; it's conceivable that this could still build with an external LLVM) * undo powerpc 9.0 file naming tweak, since we no longer support -8. * Remove patch to LLVM for powerpc now included by upstream. * Minor adjustments, checksum changes etc. Upstream changes: Version 1.74.1 (2023-12-07) =========================== - [Resolved spurious STATUS_ACCESS_VIOLATIONs in LLVM] (rust-lang/rust#118464) - [Clarify guarantees for std::mem::discriminant] (rust-lang/rust#118006) - [Fix some subtyping-related regressions] (rust-lang/rust#116415) Version 1.74.0 (2023-11-16) ========================== Language -------- - [Codify that `std::mem::Discriminant<T>` does not depend on any lifetimes in T] (rust-lang/rust#104299) - [Replace `private_in_public` lint with `private_interfaces` and `private_bounds` per RFC 2145] (rust-lang/rust#113126) Read more in [RFC 2145](https://rust-lang.github.io/rfcs/2145-type-privacy.html). - [Allow explicit `#[repr(Rust)]`] (rust-lang/rust#114201) - [closure field capturing: don't depend on alignment of packed fields] (rust-lang/rust#115315) - [Enable MIR-based drop-tracking for `async` blocks] (rust-lang/rust#107421) Compiler -------- - [stabilize combining +bundle and +whole-archive link modifiers] (rust-lang/rust#113301) - [Stabilize `PATH` option for `--print KIND=PATH`] (rust-lang/rust#114183) - [Enable ASAN/LSAN/TSAN for `*-apple-ios-macabi`] (rust-lang/rust#115644) - [Promote loongarch64-unknown-none* to Tier 2] (rust-lang/rust#115368) - [Add `i686-pc-windows-gnullvm` as a tier 3 target] (rust-lang/rust#115687) Libraries --------- - [Implement `From<OwnedFd/Handle>` for ChildStdin/out/err] (rust-lang/rust#98704) - [Implement `From<{&,&mut} [T; N]>` for `Vec<T>` where `T: Clone`] (rust-lang/rust#111278) - [impl Step for IP addresses] (rust-lang/rust#113748) - [Implement `From<[T; N]>` for `Rc<[T]>` and `Arc<[T]>`] (rust-lang/rust#114041) - [`impl TryFrom<char> for u16`] (rust-lang/rust#114065) - [Stabilize `io_error_other` feature] (rust-lang/rust#115453) - [Stabilize the `Saturating` type] (rust-lang/rust#115477) - [Stabilize const_transmute_copy] (rust-lang/rust#115520) Stabilized APIs --------------- - [`core::num::Saturating`] (https://doc.rust-lang.org/stable/std/num/struct.Saturating.html) - [`impl From<io::Stdout> for std::process::Stdio`] (https://doc.rust-lang.org/stable/std/process/struct.Stdio.html#impl-From%3CStdout%3E-for-Stdio) - [`impl From<io::Stderr> for std::process::Stdio`] (https://doc.rust-lang.org/stable/std/process/struct.Stdio.html#impl-From%3CStderr%3E-for-Stdio) - [`impl From<OwnedHandle> for std::process::Child{Stdin, Stdout, Stderr}`] (https://doc.rust-lang.org/stable/std/process/struct.Stdio.html#impl-From%3CStderr%3E-for-Stdio) - [`impl From<OwnedFd> for std::process::Child{Stdin, Stdout, Stderr}`] (https://doc.rust-lang.org/stable/std/process/struct.Stdio.html#impl-From%3CStderr%3E-for-Stdio) - [`std::ffi::OsString::from_encoded_bytes_unchecked`] (https://doc.rust-lang.org/stable/std/ffi/struct.OsString.html#method.from_encoded_bytes_unchecked) - [`std::ffi::OsString::into_encoded_bytes`] (https://doc.rust-lang.org/stable/std/ffi/struct.OsString.html#method.into_encoded_bytes) - [`std::ffi::OsStr::from_encoded_bytes_unchecked`] (https://doc.rust-lang.org/stable/std/ffi/struct.OsStr.html#method.from_encoded_bytes_unchecked) - [`std::ffi::OsStr::as_encoded_bytes`] (https://doc.rust-lang.org/stable/std/ffi/struct.OsStr.html#method.as_encoded_bytes) - [`std::io::Error::other`] (https://doc.rust-lang.org/stable/std/io/struct.Error.html#method.other) - [`impl TryFrom<char> for u16`] (https://doc.rust-lang.org/stable/std/primitive.u16.html#impl-TryFrom%3Cchar%3E-for-u16) - [`impl<T: Clone, const N: usize> From<&[T; N]> for Vec<T>`] (https://doc.rust-lang.org/stable/std/vec/struct.Vec.html#impl-From%3C%26%5BT;+N%5D%3E-for-Vec%3CT,+Global%3E) - [`impl<T: Clone, const N: usize> From<&mut [T; N]> for Vec<T>`] (https://doc.rust-lang.org/stable/std/vec/struct.Vec.html#impl-From%3C%26mut+%5BT;+N%5D%3E-for-Vec%3CT,+Global%3E) - [`impl<T, const N: usize> From<[T; N]> for Arc<[T]>`] (https://doc.rust-lang.org/stable/std/sync/struct.Arc.html#impl-From%3C%5BT;+N%5D%3E-for-Arc%3C%5BT%5D,+Global%3E) - [`impl<T, const N: usize> From<[T; N]> for Rc<[T]>`] (https://doc.rust-lang.org/stable/std/rc/struct.Rc.html#impl-From%3C%5BT;+N%5D%3E-for-Rc%3C%5BT%5D,+Global%3E) These APIs are now stable in const contexts: - [`core::mem::transmute_copy`] (https://doc.rust-lang.org/beta/std/mem/fn.transmute_copy.html) - [`str::is_ascii`] (https://doc.rust-lang.org/beta/std/primitive.str.html#method.is_ascii) - [`[u8]::is_ascii`] (https://doc.rust-lang.org/beta/std/primitive.slice.html#method.is_ascii) Cargo ----- - [fix: Set MSRV for internal packages] (rust-lang/cargo#12381) - [config: merge lists in precedence order] (rust-lang/cargo#12515) - [fix(update): Clarify meaning of --aggressive as --recursive] (rust-lang/cargo#12544) - [fix(update): Make `-p` more convenient by being positional] (rust-lang/cargo#12545) - [feat(help): Add styling to help output ] (rust-lang/cargo#12578) - [feat(pkgid): Allow incomplete versions when unambigious] (rust-lang/cargo#12614) - [feat: stabilize credential-process and registry-auth] (rust-lang/cargo#12649) - [feat(cli): Add '-n' to dry-run] (rust-lang/cargo#12660) - [Add support for `target.'cfg(..)'.linker`] (rust-lang/cargo#12535) - [Stabilize `--keep-going`] (rust-lang/cargo#12568) - [feat: Stabilize lints] (rust-lang/cargo#12648) Rustdoc ------- - [Add warning block support in rustdoc] (rust-lang/rust#106561) - [Accept additional user-defined syntax classes in fenced code blocks] (rust-lang/rust#110800) - [rustdoc-search: add support for type parameters] (rust-lang/rust#112725) - [rustdoc: show inner enum and struct in type definition for concrete type] (rust-lang/rust#114855) Compatibility Notes ------------------- - [Raise minimum supported Apple OS versions] (rust-lang/rust#104385) - [make Cell::swap panic if the Cells partially overlap] (rust-lang/rust#114795) - [Reject invalid crate names in `--extern`] (rust-lang/rust#116001) - [Don't resolve generic impls that may be shadowed by dyn built-in impls] (rust-lang/rust#114941) Internal Changes ---------------- These changes do not affect any public interfaces of Rust, but they represent significant improvements to the performance or internals of rustc and related tools. None this cycle.

rustbot assigned GuillaumeGomez Aug 15, 2023

rustbot added A-rustdoc-json Area: Rustdoc JSON backend S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Aug 15, 2023

This comment has been minimized.

Sign in to view

Urgau force-pushed the rustdoc-typedef-inner-variants branch 2 times, most recently from 8b31409 to 4255f87 Compare August 16, 2023 11:04

Urgau changed the title ~~rustdoc: show inner variants and fields in type def for concrete type~~ rustdoc: show inner enum and struct in type definition for concrete type Aug 16, 2023