From 71a4add26e39d9d1f45ab987741a99e465bb0f5e Mon Sep 17 00:00:00 2001 From: Noah Lev Date: Tue, 21 Sep 2021 19:12:10 -0700 Subject: [PATCH 1/4] Document `--show-type-layout` in the rustdoc book --- src/doc/rustdoc/src/unstable-features.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md index b55db452f12..d669230b8bf 100644 --- a/src/doc/rustdoc/src/unstable-features.md +++ b/src/doc/rustdoc/src/unstable-features.md @@ -209,6 +209,22 @@ some consideration for their stability, and names that end in a number). Giving `rustdoc` will disable this sorting and instead make it print the items in the order they appear in the source. +### `--show-type-layout`: add a section to each type's docs describing its memory layout + +Using this flag looks like this: + +```bash +$ rustdoc src/lib.rs -Z unstable-options --show-type-layout +``` + +When this flag is passed, rustdoc will add a "Layout" section at the bottom of +each type's docs page that includes a summary of the type's memory layout as +computed by rustc. For example, rustdoc will show the size in bytes that a value +of that type will take in memory. + +Note that most layout information is **completely unstable** and may even differ +between compilations. + ### `--resource-suffix`: modifying the name of CSS/JavaScript in crate docs Using this flag looks like this: From 57399e2c3999f4518f7b4b165e18bbcecc6df297 Mon Sep 17 00:00:00 2001 From: Noah Lev Date: Tue, 21 Sep 2021 19:17:09 -0700 Subject: [PATCH 2/4] Fix inconsistent heading level in the rustdoc book --- src/doc/rustdoc/src/unstable-features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md index d669230b8bf..91795997641 100644 --- a/src/doc/rustdoc/src/unstable-features.md +++ b/src/doc/rustdoc/src/unstable-features.md @@ -349,7 +349,7 @@ Some methodology notes about what rustdoc counts in this metric: Public items that are not documented can be seen with the built-in `missing_docs` lint. Private items that are not documented can be seen with Clippy's `missing_docs_in_private_items` lint. -## `-w`/`--output-format`: output format +### `-w`/`--output-format`: output format When using [`--show-coverage`](https://doc.rust-lang.org/nightly/rustdoc/unstable-features.html#--show-coverage-get-statistics-about-code-documentation-coverage), From 490a8cf573eacdc0adbe5fba0895aad4a100baca Mon Sep 17 00:00:00 2001 From: Noah Lev Date: Tue, 21 Sep 2021 19:13:15 -0700 Subject: [PATCH 3/4] rustdoc: Note that type layout may differ between compilations --- src/librustdoc/html/render/print_item.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/librustdoc/html/render/print_item.rs b/src/librustdoc/html/render/print_item.rs index 52505f2d634..b2730bf6d95 100644 --- a/src/librustdoc/html/render/print_item.rs +++ b/src/librustdoc/html/render/print_item.rs @@ -1663,7 +1663,7 @@ fn write_size_of_layout(w: &mut Buffer, layout: &Layout, tag_size: u64) { writeln!( w, "

Note: Most layout information is \ - completely unstable and may be different between compiler versions and platforms. \ + completely unstable and may even differ between compilations. \ The only exception is types with certain repr(...) attributes. \ Please see the Rust Reference’s \ “Type Layout” \ From fcb837b163dce03f77573c5bb2202958fd6584aa Mon Sep 17 00:00:00 2001 From: Noah Lev Date: Tue, 21 Sep 2021 19:15:29 -0700 Subject: [PATCH 4/4] rustdoc: Emphasize "completely unstable" --- src/librustdoc/html/render/print_item.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/librustdoc/html/render/print_item.rs b/src/librustdoc/html/render/print_item.rs index b2730bf6d95..3104cb3a3dd 100644 --- a/src/librustdoc/html/render/print_item.rs +++ b/src/librustdoc/html/render/print_item.rs @@ -1663,7 +1663,7 @@ fn write_size_of_layout(w: &mut Buffer, layout: &Layout, tag_size: u64) { writeln!( w, "

Note: Most layout information is \ - completely unstable and may even differ between compilations. \ + completely unstable and may even differ between compilations. \ The only exception is types with certain repr(...) attributes. \ Please see the Rust Reference’s \ “Type Layout” \