From 837b550238aa671a591ccf282dddeab29cadb206 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 18 May 2024 04:49:42 +0200 Subject: Merging upstream version 1.71.1+dfsg1. Signed-off-by: Daniel Baumann --- src/doc/rustdoc/src/SUMMARY.md | 1 + src/doc/rustdoc/src/how-to-read-rustdoc.md | 9 +-- src/doc/rustdoc/src/how-to-write-documentation.md | 6 +- src/doc/rustdoc/src/images/collapsed-long-item.png | Bin 0 -> 17017 bytes .../rustdoc/src/images/collapsed-trait-impls.png | Bin 0 -> 44225 bytes src/doc/rustdoc/src/lints.md | 38 ++++++++++++ .../src/read-documentation/in-doc-settings.md | 64 +++++++++++++++++++++ src/doc/rustdoc/src/references.md | 8 +-- src/doc/rustdoc/src/scraped-examples.md | 4 +- .../linking-to-items-by-name.md | 9 ++- 10 files changed, 120 insertions(+), 19 deletions(-) create mode 100644 src/doc/rustdoc/src/images/collapsed-long-item.png create mode 100644 src/doc/rustdoc/src/images/collapsed-trait-impls.png create mode 100644 src/doc/rustdoc/src/read-documentation/in-doc-settings.md (limited to 'src/doc/rustdoc') diff --git a/src/doc/rustdoc/src/SUMMARY.md b/src/doc/rustdoc/src/SUMMARY.md index 747cc629b..b512135d9 100644 --- a/src/doc/rustdoc/src/SUMMARY.md +++ b/src/doc/rustdoc/src/SUMMARY.md @@ -3,6 +3,7 @@ - [What is rustdoc?](what-is-rustdoc.md) - [Command-line arguments](command-line-arguments.md) - [How to read rustdoc output](how-to-read-rustdoc.md) + - [In-doc settings](read-documentation/in-doc-settings.md) - [How to write documentation](how-to-write-documentation.md) - [What to include (and exclude)](write-documentation/what-to-include.md) - [The `#[doc]` attribute](write-documentation/the-doc-attribute.md) diff --git a/src/doc/rustdoc/src/how-to-read-rustdoc.md b/src/doc/rustdoc/src/how-to-read-rustdoc.md index 56342f65d..ccd77fb17 100644 --- a/src/doc/rustdoc/src/how-to-read-rustdoc.md +++ b/src/doc/rustdoc/src/how-to-read-rustdoc.md @@ -43,7 +43,7 @@ including automatic and blanket implementations that `rustdoc` knows about. Subheadings, variants, fields, and many other things in this documentation are anchors and can be clicked on and deep-linked to, which is a great way to communicate exactly what you're talking about. -The typograpical character "§" appears next to lines with anchors on them +The typographical character "§" appears next to lines with anchors on them when hovered or given keyboard focus. ## The Navigation Bar @@ -68,7 +68,7 @@ Typing in the search bar instantly searches the available documentation for the string entered with a fuzzy matching algorithm that is tolerant of minor typos. -By default, the search results give are "In Names", +By default, the search results given are "In Names", meaning that the fuzzy match is made against the names of items. Matching names are shown on the left, and the first few words of their descriptions are given on the right. @@ -105,11 +105,6 @@ will match these queries: But it *does not* match `Result` or `Result>`. -### Changing displayed theme - -You can change the displayed theme by opening the settings menu (the gear -icon in the upper right) and then pick a new one from there. - ### Shortcuts Pressing `S` while focused elsewhere on the page will move focus to the diff --git a/src/doc/rustdoc/src/how-to-write-documentation.md b/src/doc/rustdoc/src/how-to-write-documentation.md index 38fd1db5c..1fa9f8144 100644 --- a/src/doc/rustdoc/src/how-to-write-documentation.md +++ b/src/doc/rustdoc/src/how-to-write-documentation.md @@ -165,15 +165,15 @@ extensions: ### Strikethrough Text may be rendered with a horizontal line through the center by wrapping the -text with two tilde characters on each side: +text with one or two tilde characters on each side: ```text -An example of ~~strikethrough text~~. +An example of ~~strikethrough text~~. You can also use ~single tildes~. ``` This example will render as: -> An example of ~~strikethrough text~~. +> An example of ~~strikethrough text~~. You can also use ~single tildes~. This follows the [GitHub Strikethrough extension][strikethrough]. diff --git a/src/doc/rustdoc/src/images/collapsed-long-item.png b/src/doc/rustdoc/src/images/collapsed-long-item.png new file mode 100644 index 000000000..c382870c6 Binary files /dev/null and b/src/doc/rustdoc/src/images/collapsed-long-item.png differ diff --git a/src/doc/rustdoc/src/images/collapsed-trait-impls.png b/src/doc/rustdoc/src/images/collapsed-trait-impls.png new file mode 100644 index 000000000..f685656e0 Binary files /dev/null and b/src/doc/rustdoc/src/images/collapsed-trait-impls.png differ diff --git a/src/doc/rustdoc/src/lints.md b/src/doc/rustdoc/src/lints.md index 45db3bb9b..fd57b0796 100644 --- a/src/doc/rustdoc/src/lints.md +++ b/src/doc/rustdoc/src/lints.md @@ -374,3 +374,41 @@ warning: this URL is not a hyperlink warning: 2 warnings emitted ``` + +## `unescaped_backticks` + +This lint is **allowed by default**. It detects backticks (\`) that are not escaped. +This usually means broken inline code. For example: + +```rust +#![warn(rustdoc::unescaped_backticks)] + +/// `add(a, b) is the same as `add(b, a)`. +pub fn add(a: i32, b: i32) -> i32 { a + b } +``` + +Which will give: + +```text +warning: unescaped backtick + --> src/lib.rs:3:41 + | +3 | /// `add(a, b) is the same as `add(b, a)`. + | ^ + | +note: the lint level is defined here + --> src/lib.rs:1:9 + | +1 | #![warn(rustdoc::unescaped_backticks)] + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +help: a previous inline code might be longer than expected + | +3 | /// `add(a, b)` is the same as `add(b, a)`. + | + +help: if you meant to use a literal backtick, escape it + | +3 | /// `add(a, b) is the same as `add(b, a)\`. + | + + +warning: 1 warning emitted +``` diff --git a/src/doc/rustdoc/src/read-documentation/in-doc-settings.md b/src/doc/rustdoc/src/read-documentation/in-doc-settings.md new file mode 100644 index 000000000..12928a4f3 --- /dev/null +++ b/src/doc/rustdoc/src/read-documentation/in-doc-settings.md @@ -0,0 +1,64 @@ +# Rustdoc in-doc settings + +Rustdoc's HTML output includes a settings menu, and this chapter describes what +each setting in this menu does. + +It can be accessed by clicking on the gear button +() in the upper right. + +## Changing displayed theme + +It is possible to change the theme. If you pick the "system preference", you +will be able to see two new sub-menus: "Preferred light theme" and "Preferred +dark theme". It means that if your system preference is set to "light", then +rustdoc will use the theme you selected in "Preferred light theme". + +## Auto-hide item contents for large items + +If the type definition contains more than 12 items, and this setting is enabled, +it'll collapse them by default. You can see them by clicking on the `[+]` button +to expand them. + +A good example of this setting in use can be seen in the +[`Iterator`](https://doc.rust-lang.org/stable/std/iter/trait.Iterator.html) doc +page: + +![Collapsed long item](../images/collapsed-long-item.png) + +## Auto-hide item methods' documentation + +If enabled, this setting will collapse all trait implementations blocks. It is +convenient if you just want an overview of all the methods available. You can +still see a method's documentation by expanding it. + +## Auto-hide trait implementation documentation + +If enabled, this setting will collapse all trait implementations blocks (you can +see them in the "Trait Implementations" section). It is convenient if you just +want an overview of all the trait implemented on a type. You can still see +a trait implementation's associated items by expanding it. + +Example: + +![Collapsed trait implementations](../images/collapsed-trait-impls.png) + +## Directly go to item in search if there is only one result + +If this setting is enabled, you will directly be taken to the result page if +your search only returned one element. Useful if you know exactly what you're +looking for and want to be taken there directly and not waste time selecting the +only search result. + +## Show line numbers on code examples + +If enabled, this setting will add line numbers to the code examples in the +documentation. It provides a visual aide for the code reading. + +## Disable keyboard shortcuts + +If this setting is enabled, the keyboard shortcuts will be disabled. It's useful +in case some of these shortcuts are already used by a web extension you're +using. + +To see the full list of the rustdoc keyboard shortcuts, you can open the help +menu (the button with the question mark on the left of the setting menu button). diff --git a/src/doc/rustdoc/src/references.md b/src/doc/rustdoc/src/references.md index 45cf4e88e..2e0cb1c0a 100644 --- a/src/doc/rustdoc/src/references.md +++ b/src/doc/rustdoc/src/references.md @@ -13,15 +13,15 @@ If you know of other great resources, please submit a pull request! ## Community - [API Guidelines] -- [Github tagged RFCs] -- [Github tagged issues] +- [GitHub tagged RFCs] +- [GitHub tagged issues] - [RFC (stalled) front page styleguide] - [Guide on how to write documentation for a Rust crate] [API Guidelines]: https://rust-lang.github.io/api-guidelines/documentation.html -[Github tagged RFCs]: https://github.com/rust-lang/rfcs/issues?q=label%3AT-rustdoc -[Github tagged issues]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+label%3AT-rustdoc +[GitHub tagged RFCs]: https://github.com/rust-lang/rfcs/issues?q=label%3AT-rustdoc +[GitHub tagged issues]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+label%3AT-rustdoc [Guide on how to write documentation for a Rust crate]: https://blog.guillaume-gomez.fr/articles/2020-03-12+Guide+on+how+to+write+documentation+for+a+Rust+crate [Learn Rust]: https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments [RFC 1574: More API Documentation Conventions]: https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html diff --git a/src/doc/rustdoc/src/scraped-examples.md b/src/doc/rustdoc/src/scraped-examples.md index d75f6d522..7197e01c8 100644 --- a/src/doc/rustdoc/src/scraped-examples.md +++ b/src/doc/rustdoc/src/scraped-examples.md @@ -24,14 +24,14 @@ Then this code snippet will be included in the documentation for `a_func`. This This feature is unstable, so you can enable it by calling Rustdoc with the unstable `rustdoc-scrape-examples` flag: ```bash -cargo doc -Zunstable-options -Zrustdoc-scrape-examples=examples +cargo doc -Zunstable-options -Zrustdoc-scrape-examples ``` To enable this feature on [docs.rs](https://docs.rs), add this to your Cargo.toml: ```toml [package.metadata.docs.rs] -cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples=examples"] +cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"] ``` diff --git a/src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md b/src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md index eb2285ef9..72157b5cd 100644 --- a/src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md +++ b/src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md @@ -88,13 +88,16 @@ fn Foo() {} ``` These prefixes will be stripped when displayed in the documentation, so `[struct@Foo]` will be -rendered as `Foo`. +rendered as `Foo`. The following prefixes are available: `struct`, `enum`, `trait`, `union`, +`mod`, `module`, `const`, `constant`, `fn`, `function`, `method`, `derive`, `type`, `value`, +`macro`, `prim` or `primitive`. You can also disambiguate for functions by adding `()` after the function name, -or for macros by adding `!` after the macro name: +or for macros by adding `!` after the macro name. The macro `!` can be followed by `()`, `{}`, +or `[]`. Example: ```rust -/// This is different from [`foo!`] +/// This is different from [`foo!()`]. fn foo() {} /// This is different from [`foo()`] -- cgit v1.2.3