From fdb28267387593974f4157dcc9558c8757805230 Mon Sep 17 00:00:00 2001 From: Eric Findlay Date: Wed, 28 Oct 2015 10:39:22 +0900 Subject: [PATCH 1/9] Added try! example to documentation.md --- src/doc/trpl/documentation.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/src/doc/trpl/documentation.md b/src/doc/trpl/documentation.md index e101d4bc0d4dc..e130109e35492 100644 --- a/src/doc/trpl/documentation.md +++ b/src/doc/trpl/documentation.md @@ -373,6 +373,36 @@ we can add the `#[macro_use]` attribute. Second, we’ll need to add our own `main()` as well. Finally, a judicious use of `#` to comment out those two things, so they don’t show up in the output. +Another case where the use of `#` is handy is when you want to ignore +error handling. Lets say you want the following, + +```rust +/// use std::io; +/// let mut input = String::new(); +/// try!(io::stdin().read_line(&mut input)); +``` + +The problem is that `try!` returns a `Result` and test functions +don't return anything so this will give a mismatched types error. + +```rust +/// A doc test using try! +/// +/// ``` +/// use std::io; +/// # fn f() -> io::Result<()> { +/// let mut input = String::new(); +/// try!(io::stdin().read_line(&mut input)); +/// # Ok(()) +/// # } +/// # f(); +/// ``` +``` + +You can get around this by wrapping the code in a function. This catches +and swallows the `Result` when running tests on the docs. This +pattern appears regularly in the standard library. + ### Running documentation tests To run the tests, either: From b2c3745229e8a0472f2a4ebede7496572e6b6d0e Mon Sep 17 00:00:00 2001 From: Eric Findlay Date: Thu, 29 Oct 2015 09:43:54 +0900 Subject: [PATCH 2/9] Added "ignore" to rustdoc example, r=steveklabnik Fixes #29234 --- src/doc/trpl/documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/trpl/documentation.md b/src/doc/trpl/documentation.md index e130109e35492..191a51dffdbfc 100644 --- a/src/doc/trpl/documentation.md +++ b/src/doc/trpl/documentation.md @@ -376,7 +376,7 @@ things, so they don’t show up in the output. Another case where the use of `#` is handy is when you want to ignore error handling. Lets say you want the following, -```rust +```rust,ignore /// use std::io; /// let mut input = String::new(); /// try!(io::stdin().read_line(&mut input)); From 46b30ccd895d6fc990474cb6f130b41d0a9b8dcf Mon Sep 17 00:00:00 2001 From: Eric Findlay Date: Sun, 8 Nov 2015 10:03:58 +0900 Subject: [PATCH 3/9] Added foo() to rustdoc example, r=steveklabnik Fixes #29234 --- src/doc/trpl/documentation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/doc/trpl/documentation.md b/src/doc/trpl/documentation.md index 191a51dffdbfc..b3f79f2f1df9c 100644 --- a/src/doc/trpl/documentation.md +++ b/src/doc/trpl/documentation.md @@ -385,17 +385,17 @@ error handling. Lets say you want the following, The problem is that `try!` returns a `Result` and test functions don't return anything so this will give a mismatched types error. -```rust +```rust,ignore /// A doc test using try! /// /// ``` /// use std::io; -/// # fn f() -> io::Result<()> { +/// # fn foo() -> io::Result<()> { /// let mut input = String::new(); /// try!(io::stdin().read_line(&mut input)); /// # Ok(()) /// # } -/// # f(); +/// # foo(); /// ``` ``` From dda7a3c2a195b7d99f4173f3636a8a7d25ca8c0c Mon Sep 17 00:00:00 2001 From: Eric Findlay Date: Sun, 8 Nov 2015 11:00:03 +0900 Subject: [PATCH 4/9] Fixed "foo()" in try! example, r=steveklabnik --- src/doc/trpl/documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/trpl/documentation.md b/src/doc/trpl/documentation.md index b3f79f2f1df9c..dc91c90b0fd62 100644 --- a/src/doc/trpl/documentation.md +++ b/src/doc/trpl/documentation.md @@ -395,8 +395,8 @@ don't return anything so this will give a mismatched types error. /// try!(io::stdin().read_line(&mut input)); /// # Ok(()) /// # } -/// # foo(); /// ``` +# fn foo() {} ``` You can get around this by wrapping the code in a function. This catches From e3433e3b519dfaddedd5f18a514604a779799da3 Mon Sep 17 00:00:00 2001 From: Stepan Koltsov Date: Sun, 8 Nov 2015 17:17:02 +0300 Subject: [PATCH 5/9] Fix outdated comment in Vec::from_iter Since commit 46068c9da, call to `reserve()` on empty vec allocates exactly requested capacity, so unroll of first iteration may help only with branch prediction. --- src/libcollections/vec.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index 716a07be2b4b2..c4e4059429f38 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -1220,8 +1220,7 @@ impl FromIterator for Vec { // expanded on this iteration in every case when the iterable is not // empty, but the loop in extend_desugared() is not going to see the // vector being full in the few subsequent loop iterations. - // So we get better branch prediction and the possibility to - // construct the vector with initial estimated capacity. + // So we get better branch prediction. let mut iterator = iterable.into_iter(); let mut vector = match iterator.next() { None => return Vec::new(), From 621e259b78fb992745c3cf194e28be5a8610a97c Mon Sep 17 00:00:00 2001 From: Kevin Butler Date: Mon, 9 Nov 2015 03:42:22 +0000 Subject: [PATCH 6/9] libstd: add example for PathBuf::push --- src/libstd/path.rs | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/src/libstd/path.rs b/src/libstd/path.rs index b9a58a117643a..6b5e16ae113b3 100644 --- a/src/libstd/path.rs +++ b/src/libstd/path.rs @@ -1013,6 +1013,21 @@ impl PathBuf { /// * if `path` has a root but no prefix (e.g. `\windows`), it /// replaces everything except for the prefix (if any) of `self`. /// * if `path` has a prefix but no root, it replaces `self`. + /// + /// # Examples + /// + /// ``` + /// use std::path::PathBuf; + /// + /// let mut path = PathBuf::new(); + /// path.push("/tmp"); + /// path.push("file.bk"); + /// assert_eq!(path, PathBuf::from("/tmp/file.bk")); + /// + /// // Pushing an absolute path replaces the current path + /// path.push("/etc/passwd"); + /// assert_eq!(path, PathBuf::from("/etc/passwd")); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn push>(&mut self, path: P) { self._push(path.as_ref()) From c618c5f36a3260351a09f4b4dc51b2e5d1359fbc Mon Sep 17 00:00:00 2001 From: Ivan Ivaschenko Date: Mon, 9 Nov 2015 17:49:30 +0200 Subject: [PATCH 7/9] Doc: Fix broken link on for-loop.html --- src/doc/trpl/dining-philosophers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/trpl/dining-philosophers.md b/src/doc/trpl/dining-philosophers.md index 5f66a5b9e297c..50d758c3a108f 100644 --- a/src/doc/trpl/dining-philosophers.md +++ b/src/doc/trpl/dining-philosophers.md @@ -232,7 +232,7 @@ also called a ‘vector’, and it’s a growable array type. We then use a [`for`][for] loop to iterate through the vector, getting a reference to each philosopher in turn. -[for]: for-loops.html +[for]: loops.html#for In the body of the loop, we call `p.eat()`, which is defined above: From 779382987761c2835fc2eaced46995a780bc4b0e Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Mon, 9 Nov 2015 13:22:16 -0800 Subject: [PATCH 8/9] Redo the README intro again --- README.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 5e208a76e0315..8eb742f0a22fc 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,9 @@ # The Rust Programming Language -Rust is a fast systems programming language that guarantees -memory safety and offers painless concurrency ([no data races]). -It does not employ a garbage collector and has minimal runtime overhead. +This is the main source code repository for [Rust]. It contains the compiler, standard library, +and documentation. -This repo contains the code for the compiler (`rustc`), as well -as standard libraries, tools and documentation for Rust. - -[no data races]: http://blog.rust-lang.org/2015/04/10/Fearless-Concurrency.html +[Rust]: https://www.rust-lang.org ## Quick Start From abb9c9008fbb253f82dfc0e7c72dcd107e820fb7 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Tue, 10 Nov 2015 01:39:23 +0100 Subject: [PATCH 9/9] Some cleanup on after #29684 * wrap to 80 cols * small grammar fix, missing 'the' --- src/libcore/iter.rs | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs index da7d673cd96b4..f8c6e3cfdd7dd 100644 --- a/src/libcore/iter.rs +++ b/src/libcore/iter.rs @@ -371,22 +371,21 @@ pub trait Iterator { /// /// # Implementation notes /// - /// It is not enforced that an iterator implementation yields the - /// declared number of elements. A buggy iterator may yield less - /// than the lower bound or more than the upper bound of elements. + /// It is not enforced that an iterator implementation yields the declared + /// number of elements. A buggy iterator may yield less than the lower bound + /// or more than the upper bound of elements. /// - /// `size_hint()` is primarily intended to be used for optimizations - /// such as reserving space for the elements of the iterator, but - /// must not be trusted to e.g. omit bounds checks in unsafe code. - /// An incorrect implementation of `size_hint()` should not lead to - /// memory safety violations. + /// `size_hint()` is primarily intended to be used for optimizations such as + /// reserving space for the elements of the iterator, but must not be + /// trusted to e.g. omit bounds checks in unsafe code. An incorrect + /// implementation of `size_hint()` should not lead to memory safety + /// violations. /// - /// That said, the implementation should provide a correct - /// estimation, because otherwise it would be a violation of the - /// trait's protocol. + /// That said, the implementation should provide a correct estimation, + /// because otherwise it would be a violation of the trait's protocol. /// - /// The default implementation returns `(0, None)` which is correct - /// for any iterator. + /// The default implementation returns `(0, None)` which is correct for any + /// iterator. /// /// # Examples /// @@ -2750,7 +2749,7 @@ pub trait ExactSizeIterator: Iterator { /// implementation, you can do so. See the [trait-level] docs for an /// example. /// - /// This function has the same safety guarantees as [`size_hint()`] + /// This function has the same safety guarantees as the [`size_hint()`] /// function. /// /// [trait-level]: trait.ExactSizeIterator.html