rustdoc: Tracking issue for command-line option `--show-type-layout`

[tgross35]

This is a tracking issue for the rustdoc show-type-layout/show_type_layout feature. This displays the layout layout (size & alignment) of types in the documentation.

This feature was formerly known as document_type_layout

Usage is described at rustdoc unstable features

Zulip thread for discussion: https://rust-lang.zulipchat.com/#narrow/stream/266220-t-rustdoc/topic/Rustdoc.20.60show-type-layout.60.20feature

Note

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.

A tracking issue is however not meant for large scale discussion, questions, or bug reports.
Instead, open a dedicated issue for the specific matter or post in the #t-rustdoc Zulip channel.

Discussion comments will get marked as off-topic or deleted.
Repeated discussions on the tracking issue may lead to the tracking issue getting locked.

Steps

• Implement the feature: rustdoc: Add unstable CLI option to show basic type layout information #83501
• Resolve any issues
  • Add support for type aliases rustdoc: Show type layout for type aliases #91265
  • Make RenderOptions fields' type into newtype instead of boolean for clarity #87752
• Adjust documentation (see instructions on rustc-dev-guide)
• Stabilization PR (see instructions on rustc-dev-guide)

Unresolved Questions

• Exact display output needs work
• How to handle layouts that differ by target (rustdoc: Tracking issue for command-line option --show-type-layout #113248 (comment))
• Handling of generic types, if any (option to select the generic type somehow or specify its layout? Seems tricky but maybe useful)

Implementation history

• Initial implementation: rustdoc: Add unstable CLI option to show basic type layout information #83501

@rustbot label +T-rustdoc

[jyn514]

How does this interact with https://doc.rust-lang.org/rustdoc/advanced-features.html#interactions-between-platform-specific-docs? Won't it cause errors or ICEs if you use it on a crate that compiles with rustdoc but not rustc, because you need to run typeck to determine layout?

[oriongonza]

For generics I'd say something along the lines of

• 1024 bytes + size_of::<T> if it contains a normal T
• 1024 bytes + size_of::<T> * 2 if it contains two T
• 1024 bytes if T is phantom

Since this is probably not something that you want in all types what about opting in?

#[doc_layout("x86_64-unknown-linux-gnu", "i686-unknown-linux-gnu")]
struct MyStruct {...}

Which gets deduplicated if it happens to be the same?

[jyn514]

i don't think it's true that the layout is some fixed offset like that. if you think about e.g. Option<fn()>, it has a completely different layout than Option<usize> because it doesn't need to store the discriminant.

[oriongonza]

Heh, that's fair.
What about keeping it simple? It can always be refined later.

#[doc_layout] // Defaults to target that is building it
struct S<T> {
  a: usize,
  b: T,
  c: Option<T>,
  d: SomePrivateStruct<T>,
  e: PhantomData<T>,
  f: SomeOtherZST<T>,
  g: [T; 10],
}

8 bytes + size_of::<T> + size_of::<Option<T> + size_of::<SomePrivateStruct<T>> + size_of::<[T; 10]>

I think that if we make it opt in it's not bad to leak the private structs.