diff --git a/compiler/rustc_middle/src/middle/region.rs b/compiler/rustc_middle/src/middle/region.rs index 38cb3c1701f92..d060549ca8137 100644 --- a/compiler/rustc_middle/src/middle/region.rs +++ b/compiler/rustc_middle/src/middle/region.rs @@ -292,20 +292,20 @@ pub struct ScopeTree { /// /// Then: /// - /// 1. From the ordering guarantee of HIR visitors (see - /// `rustc_hir::intravisit`), `D` does not dominate `U`. + /// 1. From the ordering guarantee of HIR visitors (see + /// `rustc_hir::intravisit`), `D` does not dominate `U`. /// - /// 2. Therefore, `D` is *potentially* storage-dead at `U` (because - /// we might visit `U` without ever getting to `D`). + /// 2. Therefore, `D` is *potentially* storage-dead at `U` (because + /// we might visit `U` without ever getting to `D`). /// - /// 3. However, we guarantee that at each HIR point, each - /// binding/temporary is always either always storage-live - /// or always storage-dead. This is what is being guaranteed - /// by `terminating_scopes` including all blocks where the - /// count of executions is not guaranteed. + /// 3. However, we guarantee that at each HIR point, each + /// binding/temporary is always either always storage-live + /// or always storage-dead. This is what is being guaranteed + /// by `terminating_scopes` including all blocks where the + /// count of executions is not guaranteed. /// - /// 4. By `2.` and `3.`, `D` is *statically* storage-dead at `U`, - /// QED. + /// 4. By `2.` and `3.`, `D` is *statically* storage-dead at `U`, + /// QED. /// /// This property ought to not on (3) in an essential way -- it /// is probably still correct even if we have "unrestricted" terminating diff --git a/compiler/rustc_mir_build/src/thir/pattern/_match.rs b/compiler/rustc_mir_build/src/thir/pattern/_match.rs index 04de9a7a58dda..7216d1305fd4b 100644 --- a/compiler/rustc_mir_build/src/thir/pattern/_match.rs +++ b/compiler/rustc_mir_build/src/thir/pattern/_match.rs @@ -78,20 +78,26 @@ //! new pattern `p`. //! //! For example, say we have the following: +//! //! ``` -//! // x: (Option, Result<()>) -//! match x { -//! (Some(true), _) => {} -//! (None, Err(())) => {} -//! (None, Err(_)) => {} -//! } +//! // x: (Option, Result<()>) +//! match x { +//! (Some(true), _) => {} +//! (None, Err(())) => {} +//! (None, Err(_)) => {} +//! } //! ``` +//! //! Here, the matrix `P` starts as: +//! +//! ``` //! [ //! [(Some(true), _)], //! [(None, Err(()))], //! [(None, Err(_))], //! ] +//! ``` +//! //! 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 //! all the values it covers are already covered by row 2. @@ -178,10 +184,14 @@ //! This special case is handled in `is_useful_specialized`. //! //! For example, if `P` is: +//! +//! ``` //! [ -//! [Some(true), _], -//! [None, 0], +//! [Some(true), _], +//! [None, 0], //! ] +//! ``` +//! //! 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 //! 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))` //! //! For example, if `P` is: +//! +//! ``` //! [ //! [_, true, _], //! [None, false, 1], //! ] +//! ``` +//! //! 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 //! 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))` //! //! For example, if `P` is: +//! +//! ``` //! [ //! [Some(true), _], //! [None, false], //! ] +//! ``` +//! //! 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 //! compute `U([[true, _]], [_, false])` for the `Some` constructor, and `U([[false]], @@ -1496,6 +1514,7 @@ struct PatCtxt<'tcx> { /// multiple patterns. /// /// For example, if we are constructing a witness for the match against +/// /// ``` /// 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 // constructor. // E.g., in an example like: + // // ``` // let err: io::ErrorKind = ...; // match err { // io::ErrorKind::NotFound => {}, // } // ``` + // // we don't want to show every possible IO error, but instead have only `_` as the // witness. 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(); // 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. + // // ``` // match (true, true) { // (true, true) => {} @@ -2161,10 +2183,12 @@ crate fn is_useful<'p, 'tcx>( // to do this and instead report a single `_` witness: // if the user didn't actually specify a constructor // in this arm, e.g., in + // // ``` // let x: (Direction, Direction, bool) = ...; // let (_, _, false) = x; // ``` + // // we don't want to show all 16 possible witnesses // `(, , true)` - we are // satisfied with `(_, _, true)`. In this case, diff --git a/src/doc/rustdoc/src/documentation-tests.md b/src/doc/rustdoc/src/documentation-tests.md index 18010bebcf0e7..387d86189b08f 100644 --- a/src/doc/rustdoc/src/documentation-tests.md +++ b/src/doc/rustdoc/src/documentation-tests.md @@ -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`, 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` -assumes it is `Rust` code. So the following: +Please note that by default, if no language is set for the block code, rustdoc +assumes it is Rust code. So the following: ``````markdown ```rust @@ -44,7 +44,6 @@ the `assert!` family of macros works the same as other Rust code: ```rust let 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` function! Forcing you to write `main` for every example, no matter how small, -adds friction. So `rustdoc` processes your examples slightly before -running them. Here's the full algorithm rustdoc uses to preprocess examples: +adds friction and clutters the output. So `rustdoc` processes your examples +slightly before running them. Here's the full algorithm `rustdoc` uses to +preprocess examples: 1. Some common `allow` attributes are inserted, including `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 an example block that looks like this: -```text +```ignore +/// ``` /// /// Some documentation. /// # fn foo() {} // this function will be hidden /// println!("Hello, World!"); +/// ``` ``` It will render like this: @@ -251,7 +253,7 @@ disambiguate the error type: This is an unfortunate consequence of the `?` operator adding an implicit conversion, so type inference fails because the type is not unique. Please note 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 @@ -359,7 +361,7 @@ the code with the 2015 edition. ## Syntax reference 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. 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 -[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. 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 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 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 -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, 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 `lib.rs` to test your README as part of your doctests: ```rust,ignore #![feature(external_doc)] -#[doc(include="../README.md")] +#[doc(include = "../README.md")] #[cfg(doctest)] pub struct ReadmeDoctests; ```