From 71abce1e5d99f37d52bd9b3943db980119ff286b Mon Sep 17 00:00:00 2001 From: Devin R Date: Sat, 30 Nov 2019 08:54:39 -0500 Subject: [PATCH 1/7] document match and move keywords --- src/libstd/keyword_docs.rs | 69 +++++++++++++++++++++++++++++++++++--- 1 file changed, 64 insertions(+), 5 deletions(-) diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index b0baf36308e44..6bc0af47be5af 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -812,9 +812,48 @@ mod loop_keyword { } // /// Control flow based on pattern matching. /// -/// The documentation for this keyword is [not yet complete]. Pull requests welcome! -/// -/// [not yet complete]: https://github.com/rust-lang/rust/issues/34601 +/// `match` can be used to run code conditionally. Every pattern must +/// be handled exhaustively either explicitly or by using wildcards like +/// `_` in the `match`. Since `match` is an expression values can also be +/// returned. +/// +/// ```rust +/// let opt = Option::None::; +/// let x = match opt { +/// Some(int) => int, +/// None => 10, +/// } +/// assert_eq!(x, 10); +/// +/// let a_number = Option::Some(10); +/// match a_number { +/// Some(x) if x <= 5 => println!("0 to 5 num = {}", x), +/// Some(x @ 6..=10) => println!("6 to 10 num = {}", x), +/// None => oh_no(), +/// _ => all_other_numbers(), +/// } +/// ``` +/// +/// `match` can be used to gain access to the inner members of an enum +/// and use them directly. +/// +/// ```rust +/// enum Outer { +/// Double(Option, Option), +/// Single(Option), +/// Empty +/// } +/// +/// let get_inner = Outer::Double(None, Some(String::new())); +/// match get_inner { +/// Outer::Double(None, Some(st)) => println!("{}", st), +/// Outer::Single(opt) => println!("{:?}", opt), +/// _ => the_rest(), +/// } +/// ``` +/// +/// For more information on `match` and matching in general, see the [Reference]. +/// [Reference]: ../reference/expressions/match-expr.html mod match_keyword { } #[doc(keyword = "mod")] @@ -831,9 +870,29 @@ mod mod_keyword { } // /// Capture a [closure]'s environment by value. /// -/// The documentation for this keyword is [not yet complete]. Pull requests welcome! +/// `move` converts any variables captured by reference or mutable reference +/// to owned by value variables. The three [`Fn` trait]'s mirror the ways to capture +/// variables, when `move` is used the closures is represented by the `FnOnce` trait. +/// +/// ```rust +/// +/// ``` +/// +/// `move` is often used when [threads] are involved. +/// +/// ```rust +/// let x = 5; +/// +/// std::thread::spawn(move || { +/// println!("captured {} by value", x) +/// }).join().unwrap(); +/// +/// // x is no longer available +/// ``` /// -/// [closure]: ../book/second-edition/ch13-01-closures.html +/// [`Fn` trait]: ../std/ops/trait.Fn.html +/// [closure]: ../book/ch13-01-closures.html +/// [threads]: ../book/ch16-01-threads.html#using-move-closures-with-threads /// [not yet complete]: https://github.com/rust-lang/rust/issues/34601 mod move_keyword { } From b67d6c7e1234a7227d4f903fb218a4f8a226c9f4 Mon Sep 17 00:00:00 2001 From: Devin R Date: Sat, 30 Nov 2019 08:57:33 -0500 Subject: [PATCH 2/7] add example to move --- src/libstd/keyword_docs.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index 6bc0af47be5af..24683e36b8867 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -875,7 +875,10 @@ mod mod_keyword { } /// variables, when `move` is used the closures is represented by the `FnOnce` trait. /// /// ```rust -/// +/// let capture = "hello"; +/// let closure = move || { +/// println!("we say {}", capture); +/// }; /// ``` /// /// `move` is often used when [threads] are involved. From 44f3bee17f0c9c8f7d6293db32087b70e1de72cb Mon Sep 17 00:00:00 2001 From: Devin R Date: Sat, 30 Nov 2019 09:05:46 -0500 Subject: [PATCH 3/7] add docs for move and match keywords --- src/libstd/keyword_docs.rs | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index 24683e36b8867..75a50ad875302 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -853,6 +853,7 @@ mod loop_keyword { } /// ``` /// /// For more information on `match` and matching in general, see the [Reference]. +/// /// [Reference]: ../reference/expressions/match-expr.html mod match_keyword { } @@ -892,11 +893,13 @@ mod mod_keyword { } /// /// // x is no longer available /// ``` -/// +/// +/// For more information on the `move` keyword, see the [closure]'s section +/// of the Rust book or the [threads] section +/// /// [`Fn` trait]: ../std/ops/trait.Fn.html /// [closure]: ../book/ch13-01-closures.html /// [threads]: ../book/ch16-01-threads.html#using-move-closures-with-threads -/// [not yet complete]: https://github.com/rust-lang/rust/issues/34601 mod move_keyword { } #[doc(keyword = "mut")] From d5a4c6253db548cdc428f324d2c4ab66906e5171 Mon Sep 17 00:00:00 2001 From: Devin R Date: Sat, 30 Nov 2019 10:24:04 -0500 Subject: [PATCH 4/7] remove trailing whitespace --- src/libstd/keyword_docs.rs | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index 75a50ad875302..ee098a758da9d 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -816,7 +816,7 @@ mod loop_keyword { } /// be handled exhaustively either explicitly or by using wildcards like /// `_` in the `match`. Since `match` is an expression values can also be /// returned. -/// +/// /// ```rust /// let opt = Option::None::; /// let x = match opt { @@ -824,7 +824,7 @@ mod loop_keyword { } /// None => 10, /// } /// assert_eq!(x, 10); -/// +/// /// let a_number = Option::Some(10); /// match a_number { /// Some(x) if x <= 5 => println!("0 to 5 num = {}", x), @@ -833,17 +833,17 @@ mod loop_keyword { } /// _ => all_other_numbers(), /// } /// ``` -/// -/// `match` can be used to gain access to the inner members of an enum +/// +/// `match` can be used to gain access to the inner members of an enum /// and use them directly. -/// +/// /// ```rust /// enum Outer { /// Double(Option, Option), /// Single(Option), /// Empty /// } -/// +/// /// let get_inner = Outer::Double(None, Some(String::new())); /// match get_inner { /// Outer::Double(None, Some(st)) => println!("{}", st), @@ -851,9 +851,9 @@ mod loop_keyword { } /// _ => the_rest(), /// } /// ``` -/// +/// /// For more information on `match` and matching in general, see the [Reference]. -/// +/// /// [Reference]: ../reference/expressions/match-expr.html mod match_keyword { } @@ -874,29 +874,29 @@ mod mod_keyword { } /// `move` converts any variables captured by reference or mutable reference /// to owned by value variables. The three [`Fn` trait]'s mirror the ways to capture /// variables, when `move` is used the closures is represented by the `FnOnce` trait. -/// +/// /// ```rust /// let capture = "hello"; /// let closure = move || { /// println!("we say {}", capture); /// }; /// ``` -/// +/// /// `move` is often used when [threads] are involved. -/// +/// /// ```rust /// let x = 5; -/// +/// /// std::thread::spawn(move || { /// println!("captured {} by value", x) /// }).join().unwrap(); -/// +/// /// // x is no longer available /// ``` -/// +/// /// For more information on the `move` keyword, see the [closure]'s section /// of the Rust book or the [threads] section -/// +/// /// [`Fn` trait]: ../std/ops/trait.Fn.html /// [closure]: ../book/ch13-01-closures.html /// [threads]: ../book/ch16-01-threads.html#using-move-closures-with-threads From c69be483d6604c6e9df7e1bdd43e68ceaf8cb9f0 Mon Sep 17 00:00:00 2001 From: Devin R Date: Sat, 30 Nov 2019 17:32:49 -0500 Subject: [PATCH 5/7] fix doc compile fail --- src/libstd/keyword_docs.rs | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index ee098a758da9d..b4dc97c5542d3 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -829,8 +829,9 @@ mod loop_keyword { } /// match a_number { /// Some(x) if x <= 5 => println!("0 to 5 num = {}", x), /// Some(x @ 6..=10) => println!("6 to 10 num = {}", x), -/// None => oh_no(), -/// _ => all_other_numbers(), +/// None => panic!(), +/// // all other numbers +/// _ => panic!(), /// } /// ``` /// @@ -848,7 +849,7 @@ mod loop_keyword { } /// match get_inner { /// Outer::Double(None, Some(st)) => println!("{}", st), /// Outer::Single(opt) => println!("{:?}", opt), -/// _ => the_rest(), +/// _ => panic!(), /// } /// ``` /// @@ -878,7 +879,7 @@ mod mod_keyword { } /// ```rust /// let capture = "hello"; /// let closure = move || { -/// println!("we say {}", capture); +/// println!("rust says {}", capture); /// }; /// ``` /// From 7c3befc7f92da9d714b75bb2f75433118cc60210 Mon Sep 17 00:00:00 2001 From: Devin R Date: Sat, 30 Nov 2019 18:02:19 -0500 Subject: [PATCH 6/7] add ";" for let = match --- src/libstd/keyword_docs.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index b4dc97c5542d3..c4c2063026545 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -822,7 +822,7 @@ mod loop_keyword { } /// let x = match opt { /// Some(int) => int, /// None => 10, -/// } +/// }; /// assert_eq!(x, 10); /// /// let a_number = Option::Some(10); From e638f7c1abdfff7d5d3370c9851b38dc756aef2e Mon Sep 17 00:00:00 2001 From: Devin R Date: Sun, 1 Dec 2019 19:47:54 -0500 Subject: [PATCH 7/7] add grammer fixes --- src/libstd/keyword_docs.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index c4c2063026545..5b7bef930d1d9 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -814,7 +814,7 @@ mod loop_keyword { } /// /// `match` can be used to run code conditionally. Every pattern must /// be handled exhaustively either explicitly or by using wildcards like -/// `_` in the `match`. Since `match` is an expression values can also be +/// `_` in the `match`. Since `match` is an expression, values can also be /// returned. /// /// ```rust @@ -874,7 +874,7 @@ mod mod_keyword { } /// /// `move` converts any variables captured by reference or mutable reference /// to owned by value variables. The three [`Fn` trait]'s mirror the ways to capture -/// variables, when `move` is used the closures is represented by the `FnOnce` trait. +/// variables, when `move` is used, the closures is represented by the `FnOnce` trait. /// /// ```rust /// let capture = "hello";