Skip to content

Document --show-type-layout in the rustdoc book #89164

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 22, 2021
Merged

Document --show-type-layout in the rustdoc book #89164

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
71a4add
Document `--show-type-layout` in the rustdoc book
camelid Sep 22, 2021
57399e2
Fix inconsistent heading level in the rustdoc book
camelid Sep 22, 2021
490a8cf
rustdoc: Note that type layout may differ between compilations
camelid Sep 22, 2021
fcb837b
rustdoc: Emphasize "completely unstable"
camelid Sep 22, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion src/doc/rustdoc/src/unstable-features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do you say "for example"? Isn't that the only part of the layout it shows?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, it also shows the size of each variant. The things it displays could change later, so I'd rather not have an exhaustive list that needs to be updated.


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:
Expand Down Expand Up @@ -333,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),
Expand Down
2 changes: 1 addition & 1 deletion src/librustdoc/html/render/print_item.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1663,7 +1663,7 @@ fn document_type_layout(w: &mut Buffer, cx: &Context<'_>, ty_def_id: DefId) {
writeln!(
w,
"<div class=\"warning\"><p><strong>Note:</strong> Most layout information is \
completely unstable and may be different between compiler versions and platforms. \
<strong>completely unstable</strong> and may even differ between compilations. \
The only exception is types with certain <code>repr(...)</code> attributes. \
Please see the Rust Reference’s \
<a href=\"https://doc.rust-lang.org/reference/type-layout.html\">“Type Layout”</a> \
Expand Down