nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2025-01-26 22:53:28 +00:00
Code Issues Packages Projects Releases Wiki 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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
compiler/rustc_middle/src/middle/region.rs
View File

@ -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

40
compiler/rustc_mir_build/src/thir/pattern/_match.rs
View File

@ -78,20 +78,26 @@
//! new pattern `p`.
//!
//! For example, say we have the following:
//!
//! ```
//! // x: (Option<bool>, Result<()>)
//! match x {
//! (Some(true), _) => {}
//! (None, Err(())) => {}
//! (None, Err(_)) => {}
//! }
//! // x: (Option<bool>, 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
// `(<direction-1>, <direction-2>, true)` - we are
// 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`,
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;
```