bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Clean up and improve some docs

Browse source 
* compiler docs
  * Don't format list as part of a code block
  * Clean up some other formatting
* rustdoc book
  * Update CommonMark spec version to latest (0.28 -> 0.29)
  * Clean up some various wording and formatting
This commit is contained in:
Camelid 2020-10-18 21:54:10 -07:00
parent b1496c6e60
commit d725da129e
3 changed files with 58 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

24
compiler/rustc_mir_build/src/thir/pattern/_match.rs
View file

@ -78,6 +78,7 @@
//! new pattern `p`. //! new pattern `p`.
//! //!
//! For example, say we have the following: //! For example, say we have the following:
//!
//! ``` //! ```
//! // x: (Option<bool>, Result<()>) //! // x: (Option<bool>, Result<()>)
//! match x { //! match x {
@ -86,12 +87,17 @@
//! (None, Err(_)) => {} //! (None, Err(_)) => {}
//! } //! }
//! ``` //! ```
//!
//! Here, the matrix `P` starts as: //! Here, the matrix `P` starts as:
//!
//! ```
//! [ //! [
//! [(Some(true), _)], //! [(Some(true), _)],
//! [(None, Err(()))], //! [(None, Err(()))],
//! [(None, Err(_))], //! [(None, Err(_))],
//! ] //! ]
//! ```
//!
//! We can tell it's not exhaustive, because `U(P, _)` is true (we're not covering //! We can tell it's not exhaustive, because `U(P, _)` is true (we're not covering
//! `[(Some(false), _)]`, for instance). In addition, row 3 is not useful, because //! `[(Some(false), _)]`, for instance). In addition, row 3 is not useful, because
//! all the values it covers are already covered by row 2. //! all the values it covers are already covered by row 2.
@ -178,10 +184,14 @@
//! This special case is handled in `is_useful_specialized`. //! This special case is handled in `is_useful_specialized`.
//! //!
//! For example, if `P` is: //! For example, if `P` is:
//!
//! ```
//! [ //! [
//! [Some(true), _], //! [Some(true), _],
//! [None, 0], //! [None, 0],
//! ] //! ]
//! ```
//!
//! and `p` is [Some(false), 0], then we don't care about row 2 since we know `p` only //! and `p` is [Some(false), 0], then we don't care about row 2 since we know `p` only
//! matches values that row 2 doesn't. For row 1 however, we need to dig into the //! matches values that row 2 doesn't. For row 1 however, we need to dig into the
//! arguments of `Some` to know whether some new value is covered. So we compute //! arguments of `Some` to know whether some new value is covered. So we compute
@ -198,10 +208,14 @@
//! `U(P, p) := U(D(P), D(p))` //! `U(P, p) := U(D(P), D(p))`
//! //!
//! For example, if `P` is: //! For example, if `P` is:
//!
//! ```
//! [ //! [
//! [_, true, _], //! [_, true, _],
//! [None, false, 1], //! [None, false, 1],
//! ] //! ]
//! ```
//!
//! and `p` is [_, false, _], the `Some` constructor doesn't appear in `P`. So if we //! and `p` is [_, false, _], the `Some` constructor doesn't appear in `P`. So if we
//! only had row 2, we'd know that `p` is useful. However row 1 starts with a //! only had row 2, we'd know that `p` is useful. However row 1 starts with a
//! wildcard, so we need to check whether `U([[true, _]], [false, 1])`. //! wildcard, so we need to check whether `U([[true, _]], [false, 1])`.
@ -215,10 +229,14 @@
//! `U(P, p) := ∃(k ϵ constructors) U(S(k, P), S(k, p))` //! `U(P, p) := ∃(k ϵ constructors) U(S(k, P), S(k, p))`
//! //!
//! For example, if `P` is: //! For example, if `P` is:
//!
//! ```
//! [ //! [
//! [Some(true), _], //! [Some(true), _],
//! [None, false], //! [None, false],
//! ] //! ]
//! ```
//!
//! and `p` is [_, false], both `None` and `Some` constructors appear in the first //! and `p` is [_, false], both `None` and `Some` constructors appear in the first
//! components of `P`. We will therefore try popping both constructors in turn: we //! components of `P`. We will therefore try popping both constructors in turn: we
//! compute `U([[true, _]], [_, false])` for the `Some` constructor, and `U([[false]], //! compute `U([[true, _]], [_, false])` for the `Some` constructor, and `U([[false]],
@ -1496,6 +1514,7 @@ struct PatCtxt<'tcx> {
/// multiple patterns. /// multiple patterns.
/// ///
/// For example, if we are constructing a witness for the match against /// For example, if we are constructing a witness for the match against
///
/// ``` /// ```
/// struct Pair(Option<(u32, u32)>, bool); /// struct Pair(Option<(u32, u32)>, bool);
/// ///
@ -1619,12 +1638,14 @@ fn all_constructors<'a, 'tcx>(
// actually match against them all themselves. So we always return only the fictitious // actually match against them all themselves. So we always return only the fictitious
// constructor. // constructor.
// E.g., in an example like: // E.g., in an example like:
//
// ``` // ```
// let err: io::ErrorKind = ...; // let err: io::ErrorKind = ...;
// match err { // match err {
// io::ErrorKind::NotFound => {}, // io::ErrorKind::NotFound => {},
// } // }
// ``` // ```
//
// we don't want to show every possible IO error, but instead have only `_` as the // we don't want to show every possible IO error, but instead have only `_` as the
// witness. // witness.
let is_declared_nonexhaustive = cx.is_foreign_non_exhaustive_enum(pcx.ty); let is_declared_nonexhaustive = cx.is_foreign_non_exhaustive_enum(pcx.ty);
@ -2017,6 +2038,7 @@ crate fn is_useful<'p, 'tcx>(
let mut unreachable_branches = Vec::new(); let mut unreachable_branches = Vec::new();
// Subpatterns that are unreachable from all branches. E.g. in the following case, the last // Subpatterns that are unreachable from all branches. E.g. in the following case, the last
// `true` is unreachable only from one branch, so it is overall reachable. // `true` is unreachable only from one branch, so it is overall reachable.
//
// ``` // ```
// match (true, true) { // match (true, true) {
// (true, true) => {} // (true, true) => {}
@ -2161,10 +2183,12 @@ crate fn is_useful<'p, 'tcx>(
// to do this and instead report a single `_` witness: // to do this and instead report a single `_` witness:
// if the user didn't actually specify a constructor // if the user didn't actually specify a constructor
// in this arm, e.g., in // in this arm, e.g., in
//
// ``` // ```
// let x: (Direction, Direction, bool) = ...; // let x: (Direction, Direction, bool) = ...;
// let (_, _, false) = x; // let (_, _, false) = x;
// ``` // ```
//
// we don't want to show all 16 possible witnesses // we don't want to show all 16 possible witnesses
// `(<direction-1>, <direction-2>, true)` - we are // `(<direction-1>, <direction-2>, true)` - we are
// satisfied with `(_, _, true)`. In this case, // satisfied with `(_, _, true)`. In this case,

28
src/doc/rustdoc/src/documentation-tests.md
View file

@ -16,8 +16,8 @@ The basic idea is this:
The triple backticks start and end code blocks. If this were in a file named `foo.rs`, The triple backticks start and end code blocks. If this were in a file named `foo.rs`,
running `rustdoc --test foo.rs` will extract this example, and then run it as a test. running `rustdoc --test foo.rs` will extract this example, and then run it as a test.
Please note that by default, if no language is set for the block code, `rustdoc` Please note that by default, if no language is set for the block code, rustdoc
assumes it is `Rust` code. So the following: assumes it is Rust code. So the following:
``````markdown ``````markdown
```rust ```rust
@ -44,7 +44,6 @@ the `assert!` family of macros works the same as other Rust code:
```rust ```rust
let foo = "foo"; let foo = "foo";
assert_eq!(foo, "foo"); assert_eq!(foo, "foo");
``` ```
@ -55,8 +54,9 @@ the code panics and the doctest fails.
In the example above, you'll note something strange: there's no `main` In the example above, you'll note something strange: there's no `main`
function! Forcing you to write `main` for every example, no matter how small, function! Forcing you to write `main` for every example, no matter how small,
adds friction. So `rustdoc` processes your examples slightly before adds friction and clutters the output. So `rustdoc` processes your examples
running them. Here's the full algorithm rustdoc uses to preprocess examples: slightly before running them. Here's the full algorithm `rustdoc` uses to
preprocess examples:
1. Some common `allow` attributes are inserted, including 1. Some common `allow` attributes are inserted, including
`unused_variables`, `unused_assignments`, `unused_mut`, `unused_variables`, `unused_assignments`, `unused_mut`,
@ -78,10 +78,12 @@ Sometimes, you need some setup code, or other things that would distract
from your example, but are important to make the tests work. Consider from your example, but are important to make the tests work. Consider
an example block that looks like this: an example block that looks like this:
```text ```ignore
/// ```
/// /// Some documentation. /// /// Some documentation.
/// # fn foo() {} // this function will be hidden /// # fn foo() {} // this function will be hidden
/// println!("Hello, World!"); /// println!("Hello, World!");
/// ```
``` ```
It will render like this: It will render like this:
@ -251,7 +253,7 @@ disambiguate the error type:
This is an unfortunate consequence of the `?` operator adding an implicit This is an unfortunate consequence of the `?` operator adding an implicit
conversion, so type inference fails because the type is not unique. Please note conversion, so type inference fails because the type is not unique. Please note
that you must write the `(())` in one sequence without intermediate whitespace that you must write the `(())` in one sequence without intermediate whitespace
so that rustdoc understands you want an implicit `Result`-returning function. so that `rustdoc` understands you want an implicit `Result`-returning function.
## Documenting macros ## Documenting macros
@ -359,7 +361,7 @@ the code with the 2015 edition.
## Syntax reference ## Syntax reference
The *exact* syntax for code blocks, including the edge cases, can be found The *exact* syntax for code blocks, including the edge cases, can be found
in the [Fenced Code Blocks](https://spec.commonmark.org/0.28/#fenced-code-blocks) in the [Fenced Code Blocks](https://spec.commonmark.org/0.29/#fenced-code-blocks)
section of the CommonMark specification. section of the CommonMark specification.
Rustdoc also accepts *indented* code blocks as an alternative to fenced Rustdoc also accepts *indented* code blocks as an alternative to fenced
@ -372,7 +374,7 @@ can indent each line by four or more spaces.
`````` ``````
These, too, are documented in the CommonMark specification, in the These, too, are documented in the CommonMark specification, in the
[Indented Code Blocks](https://spec.commonmark.org/0.28/#indented-code-blocks) [Indented Code Blocks](https://spec.commonmark.org/0.29/#indented-code-blocks)
section. section.
However, it's preferable to use fenced code blocks over indented code blocks. However, it's preferable to use fenced code blocks over indented code blocks.
@ -388,7 +390,7 @@ documentation. To this end, Rustdoc allows you to have certain items only appear
collecting doctests, so you can utilize doctest functionality without forcing the test to appear in collecting doctests, so you can utilize doctest functionality without forcing the test to appear in
docs, or to find an arbitrary private item to include it on. docs, or to find an arbitrary private item to include it on.
When compiling a crate for use in doctests (with `--test` option), rustdoc will set `cfg(doctest)`. When compiling a crate for use in doctests (with `--test` option), `rustdoc` will set `#[cfg(doctest)]`.
Note that they will still link against only the public items of your crate; if you need to test Note that they will still link against only the public items of your crate; if you need to test
private items, you need to write a unit test. private items, you need to write a unit test.
@ -407,18 +409,18 @@ pub struct MyStructOnlyTakesUsize;
``` ```
Note that the struct `MyStructOnlyTakesUsize` here isn't actually part of your public crate Note that the struct `MyStructOnlyTakesUsize` here isn't actually part of your public crate
API. The use of `#[cfg(doctest)]` makes sure that this struct only exists while rustdoc is API. The use of `#[cfg(doctest)]` makes sure that this struct only exists while `rustdoc` is
collecting doctests. This means that its doctest is executed when `--test` is passed to rustdoc, collecting doctests. This means that its doctest is executed when `--test` is passed to rustdoc,
but is hidden from the public documentation. but is hidden from the public documentation.
Another possible use of `cfg(doctest)` is to test doctests that are included in your README file Another possible use of `#[cfg(doctest)]` is to test doctests that are included in your README file
without including it in your main documentation. For example, you could write this into your without including it in your main documentation. For example, you could write this into your
`lib.rs` to test your README as part of your doctests: `lib.rs` to test your README as part of your doctests:
```rust,ignore ```rust,ignore
#![feature(external_doc)] #![feature(external_doc)]
#[doc(include="../README.md")] #[doc(include = "../README.md")]
#[cfg(doctest)] #[cfg(doctest)]
pub struct ReadmeDoctests; pub struct ReadmeDoctests;
``` ```