From 981ac6d332ff19812532a4f64b6dc3f49114f75a Mon Sep 17 00:00:00 2001 From: Luke Jones Date: Mon, 21 Dec 2015 09:53:07 +1300 Subject: [PATCH 1/4] Rewrite paragraph in 'match' to be more concise and readable. Start correcting use of ':' in sentences. The colon `:` should be used only when the sentence preceeding it is a complete sentence. If this is not the case, then a `;` should be used; this denotes that the following fragment is a part of the previous fragment. --- src/doc/book/documentation.md | 8 ++++---- src/doc/book/match.md | 18 +++++------------- src/doc/book/patterns.md | 2 +- 3 files changed, 10 insertions(+), 18 deletions(-) diff --git a/src/doc/book/documentation.md b/src/doc/book/documentation.md index 0d0fd8cf1d0a6..fab8f22c6d0b3 100644 --- a/src/doc/book/documentation.md +++ b/src/doc/book/documentation.md @@ -9,7 +9,7 @@ document your project. The Rust distribution includes a tool, `rustdoc`, that generates documentation. `rustdoc` is also used by Cargo through `cargo doc`. -Documentation can be generated in two ways: from source code, and from +Documentation can be generated in two ways; from source code, and from standalone Markdown files. ## Documenting source code @@ -73,7 +73,7 @@ hello.rs:4 } ``` This [unfortunate error](https://github.com/rust-lang/rust/issues/22547) is -correct: documentation comments apply to the thing after them, and there's +correct; documentation comments apply to the thing after them, and there's nothing after that last comment. [rc-new]: https://doc.rust-lang.org/nightly/std/rc/struct.Rc.html#method.new @@ -385,7 +385,7 @@ error handling. Lets say you want the following, ```rust,ignore /// use std::io; -/// let mut input = String::new(); +/// let mut input = String::new(); /// try!(io::stdin().read_line(&mut input)); ``` @@ -398,7 +398,7 @@ don't return anything so this will give a mismatched types error. /// ``` /// use std::io; /// # fn foo() -> io::Result<()> { -/// let mut input = String::new(); +/// let mut input = String::new(); /// try!(io::stdin().read_line(&mut input)); /// # Ok(()) /// # } diff --git a/src/doc/book/match.md b/src/doc/book/match.md index 113e218883b34..ce176e40b9022 100644 --- a/src/doc/book/match.md +++ b/src/doc/book/match.md @@ -23,26 +23,18 @@ match x { `match` takes an expression and then branches based on its value. Each ‘arm’ of the branch is of the form `val => expression`. When the value matches, that arm’s expression will be evaluated. It’s called `match` because of the term ‘pattern -matching’, which `match` is an implementation of. There’s an [entire section on +matching’, which `match` is an implementation of. There’s a [separate section on patterns][patterns] that covers all the patterns that are possible here. [patterns]: patterns.html -So what’s the big advantage? Well, there are a few. First of all, `match` -enforces ‘exhaustiveness checking’. Do you see that last arm, the one with the -underscore (`_`)? If we remove that arm, Rust will give us an error: +One of the many advantages of `match` is it enforces ‘exhaustiveness checking’. For example if we remove the last arm with the underscore `_`, the compiler will give us an error: ```text error: non-exhaustive patterns: `_` not covered ``` -In other words, Rust is trying to tell us we forgot a value. Because `x` is an -integer, Rust knows that it can have a number of different values – for -example, `6`. Without the `_`, however, there is no arm that could match, and -so Rust refuses to compile the code. `_` acts like a ‘catch-all arm’. If none -of the other arms match, the arm with `_` will, and since we have this -catch-all arm, we now have an arm for every possible value of `x`, and so our -program will compile successfully. +Rust is telling us that we forgot a value. The compiler infers from `x` that it can have any positive 32bit value; for example 1 to 2,147,483,647. The `_` acts as a 'catch-all', and will catch all possible values that *aren't* specified in an arm of `match`. As you can see with the previous example, we provide `match` arms for integers 1-5, if `x` is 6 or any other value, then it is caught by `_`. `match` is also an expression, which means we can use it on the right-hand side of a `let` binding or directly where an expression is used: @@ -60,7 +52,7 @@ let number = match x { }; ``` -Sometimes it’s a nice way of converting something from one type to another. +Sometimes it’s a nice way of converting something from one type to another; in this example the integers are converted to `String`. # Matching on enums @@ -91,7 +83,7 @@ fn process_message(msg: Message) { Again, the Rust compiler checks exhaustiveness, so it demands that you have a match arm for every variant of the enum. If you leave one off, it -will give you a compile-time error unless you use `_`. +will give you a compile-time error unless you use `_` or provide all possible arms. Unlike the previous uses of `match`, you can’t use the normal `if` statement to do this. You can use the [`if let`][if-let] statement, diff --git a/src/doc/book/patterns.md b/src/doc/book/patterns.md index 43f1bd2529fd2..6d6044c53005f 100644 --- a/src/doc/book/patterns.md +++ b/src/doc/book/patterns.md @@ -7,7 +7,7 @@ on a whirlwind tour of all of the things patterns can do! [bindings]: variable-bindings.html [match]: match.html -A quick refresher: you can match against literals directly, and `_` acts as an +A quick refresher; you can match against literals directly, and `_` acts as an ‘any’ case: ```rust From fc4bb5f77060b5822f25edbabbdf7a1d48a7f8fe Mon Sep 17 00:00:00 2001 From: Luke Jones Date: Mon, 21 Dec 2015 16:20:20 +1300 Subject: [PATCH 2/4] Correct line wrap --- src/doc/book/match.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/src/doc/book/match.md b/src/doc/book/match.md index ce176e40b9022..acffaf4544b10 100644 --- a/src/doc/book/match.md +++ b/src/doc/book/match.md @@ -28,13 +28,19 @@ patterns][patterns] that covers all the patterns that are possible here. [patterns]: patterns.html -One of the many advantages of `match` is it enforces ‘exhaustiveness checking’. For example if we remove the last arm with the underscore `_`, the compiler will give us an error: +One of the many advantages of `match` is it enforces ‘exhaustiveness checking’. +For example if we remove the last arm with the underscore `_`, the compiler will +give us an error: ```text error: non-exhaustive patterns: `_` not covered ``` -Rust is telling us that we forgot a value. The compiler infers from `x` that it can have any positive 32bit value; for example 1 to 2,147,483,647. The `_` acts as a 'catch-all', and will catch all possible values that *aren't* specified in an arm of `match`. As you can see with the previous example, we provide `match` arms for integers 1-5, if `x` is 6 or any other value, then it is caught by `_`. +Rust is telling us that we forgot a value. The compiler infers from `x` that it +can have any positive 32bit value; for example 1 to 2,147,483,647. The `_` acts +as a 'catch-all', and will catch all possible values that *aren't* specified in +an arm of `match`. As you can see with the previous example, we provide `match` +arms for integers 1-5, if `x` is 6 or any other value, then it is caught by `_`. `match` is also an expression, which means we can use it on the right-hand side of a `let` binding or directly where an expression is used: @@ -52,7 +58,8 @@ let number = match x { }; ``` -Sometimes it’s a nice way of converting something from one type to another; in this example the integers are converted to `String`. +Sometimes it’s a nice way of converting something from one type to another; in +this example the integers are converted to `String`. # Matching on enums @@ -83,7 +90,8 @@ fn process_message(msg: Message) { Again, the Rust compiler checks exhaustiveness, so it demands that you have a match arm for every variant of the enum. If you leave one off, it -will give you a compile-time error unless you use `_` or provide all possible arms. +will give you a compile-time error unless you use `_` or provide all possible +arms. Unlike the previous uses of `match`, you can’t use the normal `if` statement to do this. You can use the [`if let`][if-let] statement, From 1bb131cdcad7c954531f51c3f318a92e11000d75 Mon Sep 17 00:00:00 2001 From: Luke Jones Date: Mon, 21 Dec 2015 16:20:56 +1300 Subject: [PATCH 3/4] Update patterns.md --- src/doc/book/patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/patterns.md b/src/doc/book/patterns.md index 6d6044c53005f..43f1bd2529fd2 100644 --- a/src/doc/book/patterns.md +++ b/src/doc/book/patterns.md @@ -7,7 +7,7 @@ on a whirlwind tour of all of the things patterns can do! [bindings]: variable-bindings.html [match]: match.html -A quick refresher; you can match against literals directly, and `_` acts as an +A quick refresher: you can match against literals directly, and `_` acts as an ‘any’ case: ```rust From 1522350ecc2e9c9f35ece84919924cb319c0e69e Mon Sep 17 00:00:00 2001 From: Luke Jones Date: Mon, 21 Dec 2015 16:24:17 +1300 Subject: [PATCH 4/4] Revert to colon. The text is introducing a list. --- src/doc/book/documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/documentation.md b/src/doc/book/documentation.md index fab8f22c6d0b3..86c07f9cf6c18 100644 --- a/src/doc/book/documentation.md +++ b/src/doc/book/documentation.md @@ -9,7 +9,7 @@ document your project. The Rust distribution includes a tool, `rustdoc`, that generates documentation. `rustdoc` is also used by Cargo through `cargo doc`. -Documentation can be generated in two ways; from source code, and from +Documentation can be generated in two ways: from source code, and from standalone Markdown files. ## Documenting source code