Merge branch 'master' into jsjoeio/108-doc-attribute-examples

Author: jsjoeio

.gitignore

@@ -1 +1,4 @@
 book
+
+# Auto-generated files from macOS
+.DS_Store

src/SUMMARY.md

@@ -213,3 +213,4 @@
 
 - [Meta](meta.md)
     - [Documentation](meta/doc.md)
+    - [Playpen](meta/playpen.md)

src/error/multiple_error_types/boxing_errors.md

@@ -24,16 +24,7 @@ impl fmt::Display for EmptyVec {
     }
 }
 
-impl error::Error for EmptyVec {
-    fn description(&self) -> &str {
-        "invalid first item to double"
-    }
-
-    fn cause(&self) -> Option<&(dyn error::Error)> {
-        // Generic error, underlying cause isn't tracked.
-        None
-    }
-}
+impl error::Error for EmptyVec {}
 
 fn double_first(vec: Vec<&str>) -> Result<i32> {
     vec.first()

src/error/multiple_error_types/define_error_type.md

@@ -16,7 +16,6 @@ Rust allows us to define our own error types. In general, a "good" error type:
 * Composes well with other errors
 
 ```rust,editable
-use std::error;
 use std::fmt;
 
 type Result<T> = std::result::Result<T, DoubleError>;
@@ -38,14 +37,6 @@ impl fmt::Display for DoubleError {
     }
 }
 
-// This is important for other errors to wrap this one.
-impl error::Error for DoubleError {
-    fn source(&self) -> Option<&(dyn error::Error + 'static)> {
-        // Generic error, underlying cause isn't tracked.
-        None
-    }
-}
-
 fn double_first(vec: Vec<&str>) -> Result<i32> {
     vec.first()
         // Change the error to our new type.

src/error/multiple_error_types/reenter_question_mark.md

@@ -38,16 +38,7 @@ impl fmt::Display for EmptyVec {
     }
 }
 
-impl error::Error for EmptyVec {
-    fn description(&self) -> &str {
-        "invalid first item to double"
-    }
-
-    fn cause(&self) -> Option<&error::Error> {
-        // Generic error, underlying cause isn't tracked.
-        None
-    }
-}
+impl error::Error for EmptyVec {}
 
 // The same structure as before but rather than chain all `Results`
 // and `Options` along, we `?` to get the inner value out immediately.

src/meta.md

@@ -4,9 +4,9 @@ Some topics aren't exactly relevant to how you program but provide you
 tooling or infrastructure support which just makes things better for
 everyone. These topics include:
 
-* Documentation: Generate library documentation for users via the included
-`rustdoc`.
-* Testing: Create testsuites for libraries to give confidence that your
-library does exactly what it's supposed to.
-* Benchmarking: Create benchmarks for functionality to be confident that
-they run quickly.
+- [Documentation][doc]: Generate library documentation for users via the included
+  `rustdoc`.
+- [Playpen][playpen]: Integrate the Rust Playpen(also known as the Rust Playground) in your documentation.
+
+[doc]: meta/doc.md
+[playpen]: meta/playpen.md

src/meta/doc.md

@@ -9,7 +9,7 @@ These commands will appropriately invoke `rustdoc` (and `rustc`) as required.
 ## Doc comments
 
 Doc comments are very useful for big projects that require documentation. When
-running Rustdoc, these are the comments that get compiled into
+running `rustdoc`, these are the comments that get compiled into
 documentation. They are denoted by a `///`, and support [Markdown].
 
 ```rust,editable,ignore
@@ -32,7 +32,7 @@ impl Person {
     ///
     /// ```
     /// // You can have rust code between fences inside the comments
-    /// // If you pass --test to Rustdoc, it will even test it for you!
+    /// // If you pass --test to `rustdoc`, it will even test it for you!
     /// use doc::Person;
     /// let person = Person::new("name");
     /// ```
@@ -57,7 +57,7 @@ fn main() {
 }
 ```
 
-To run the tests, first build the code as a library, then tell rustdoc where
+To run the tests, first build the code as a library, then tell `rustdoc` where
 to find the library so it can link it into each doctest program:
 
 ```shell
@@ -103,10 +103,12 @@ Using this tells `rustdoc` not to include this in documentation:
 pub use self::async_await::*;
 ```
 
+For documentation, `rustdoc` is widely used by the community. It's what is used to generate the [std library docs](https://doc.rust-lang.org/std/).
+
 ### See also:
 
 * [The Rust Book: Making Useful Documentation Comments][book]
-* [The Rustdoc Book][rustdoc-book]
+* [The rustdoc Book][rustdoc-book]
 * [The Reference: Doc comments][ref-comments]
 * [RFC 1574: API Documentation Conventions][api-conv]
 * [RFC 1946: Relative links to other items from doc comments (intra-rustdoc links)][intra-links]

src/meta/playpen.md

@@ -0,0 +1,38 @@
+# Playpen
+
+The [Rust Playpen](https://github.com/rust-lang/rust-playpen) is a way to experiment with Rust code through a web interface. This project is now commonly referred to as [Rust Playground](https://play.rust-lang.org/).
+
+## Using it with `mdbook`
+
+In [`mdbook`][mdbook], you can make code examples playable and editable.
+
+```rust,editable
+fn main() {
+    println!("Hello World!");
+}
+```
+
+This allows the reader to both run your code sample, but also modify and tweak it. The key here is the adding the word `editable` to your codefence block separated by a comma.
+
+````markdown
+```rust,editable
+//...place your code here
+```
+````
+
+## Using it with docs
+
+You may have noticed in some of the [official Rust docs][official-rust-docs] a button that says "Run", which opens the code sample up in a new tab in Rust Playground. This feature is enabled if you use the #[doc] attribute called [`html_playground_url`][html-playground-url].
+
+### See also:
+
+- [The Rust Playground][rust-playground]
+- [The next-gen playpen][next-gen-playpen]
+- [The rustdoc Book][rustdoc-book]
+
+[rust-playground]: https://play.rust-lang.org/
+[next-gen-playpen]: https://github.com/integer32llc/rust-playground/
+[mdbook]: https://github.com/rust-lang/mdBook
+[official-rust-docs]: https://doc.rust-lang.org/core/
+[rustdoc-book]: https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html
+[html-playground-url]: https://doc.rust-lang.org/rustdoc/the-doc-attribute.html#html_playground_url

src/scope/lifetime/static_lifetime.md

@@ -1,10 +1,27 @@
 # Static
 
-A `'static` lifetime is the longest possible lifetime, and lasts for 
-the lifetime of the running program. A `'static` lifetime may also be 
-coerced to a shorter lifetime. There are two ways to make a variable 
-with `'static` lifetime, and both are stored in the read-only memory
-of the binary:
+Rust has a few reserved lifetime names. One of those is `'static`. You
+might encounter it in two situations:
+
+```rust, editable
+// A reference with 'static lifetime:
+let s: &'static str = "hello world";
+
+// 'static as part of a trait bound:
+fn generic<T>(x: T) where T: 'static {}
+```
+
+Both are related but subtly different and this is a common source for
+confusion when learning Rust. Here are some examples for each situation:
+
+## Reference lifetime
+
+As a reference lifetime `'static` indicates that the data pointed to by
+the reference lives for the entire lifetime of the running program.
+It can still be coerced to a shorter lifetime.
+
+There are two ways to make a variable with `'static` lifetime, and both
+are stored in the read-only memory of the binary:
 
 * Make a constant with the `static` declaration.
 * Make a `string` literal which has type: `&'static str`.
@@ -15,7 +32,7 @@ See the following example for a display of each method:
 // Make a constant with `'static` lifetime.
 static NUM: i32 = 18;
 
-// Returns a reference to `NUM` where its `'static` 
+// Returns a reference to `NUM` where its `'static`
 // lifetime is coerced to that of the input argument.
 fn coerce_static<'a>(_: &'a i32) -> &'a i32 {
     &NUM
@@ -30,7 +47,7 @@ fn main() {
         // When `static_string` goes out of scope, the reference
         // can no longer be used, but the data remains in the binary.
     }
-    
+
     {
         // Make an integer to use for `coerce_static`:
         let lifetime_num = 9;
@@ -40,13 +57,56 @@ fn main() {
 
         println!("coerced_static: {}", coerced_static);
     }
-    
+
     println!("NUM: {} stays accessible!", NUM);
 }
 ```
 
+## Trait bound
+
+As a trait bound, it means the type does not contain any non-static
+references. Eg. the receiver can hold on to the type for as long as
+they want and it will never become invalid until they drop it.
+
+It's important to understand this means that any owned data always passes
+a `'static` lifetime bound, but a reference to that owned data generally
+does not:
+
+```rust,editable,compile_fail
+use std::fmt::Debug;
+
+fn print_it( input: impl Debug + 'static )
+{
+    println!( "'static value passed in is: {:?}", input );
+}
+
+fn use_it()
+{
+    // i is owned and contains no references, thus it's 'static:
+    let i = 5;
+    print_it(i);
+
+    // oops, &i only has the lifetime defined by the scope of
+    // use_it(), so it's not 'static:
+    print_it(&i);
+}
+```
+The compiler will tell you:
+```ignore
+error[E0597]: `i` does not live long enough
+  --> src/lib.rs:15:15
+   |
+15 |     print_it(&i);
+   |     ---------^^--
+   |     |         |
+   |     |         borrowed value does not live long enough
+   |     argument requires that `i` is borrowed for `'static`
+16 | }
+   | - `i` dropped here while still borrowed
+```
+
 ### See also:
 
 [`'static` constants][static_const]
 
-[static_const]: ../../custom_types/constants.md
+[static_const]: ../../custom_types/constants.md

src/std_misc/file/create.md

@@ -14,24 +14,23 @@ cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
 proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
 ";
 
-use std::error::Error;
 use std::fs::File;
 use std::io::prelude::*;
 use std::path::Path;
 
 fn main() {
-    let path = Path::new("out/lorem_ipsum.txt");
+    let path = Path::new("lorem_ipsum.txt");
     let display = path.display();
 
     // Open a file in write-only mode, returns `io::Result<File>`
     let mut file = match File::create(&path) {
-        Err(why) => panic!("couldn't create {}: {}", display, why.description()),
+        Err(why) => panic!("couldn't create {}: {}", display, why),
         Ok(file) => file,
     };
 
     // Write the `LOREM_IPSUM` string to `file`, returns `io::Result<()>`
     match file.write_all(LOREM_IPSUM.as_bytes()) {
-        Err(why) => panic!("couldn't write to {}: {}", display, why.description()),
+        Err(why) => panic!("couldn't write to {}: {}", display, why),
         Ok(_) => println!("successfully wrote to {}", display),
     }
 }
@@ -40,10 +39,9 @@ fn main() {
 Here's the expected successful output:
 
 ```shell
-$ mkdir out
 $ rustc create.rs && ./create
-successfully wrote to out/lorem_ipsum.txt
-$ cat out/lorem_ipsum.txt
+successfully wrote to lorem_ipsum.txt
+$ cat lorem_ipsum.txt
 Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
 tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
 quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo

src/std_misc/file/open.md

@@ -6,7 +6,6 @@ A `File` owns a resource, the file descriptor and takes care of closing the
 file when it is `drop`ed.
 
 ```rust,editable,ignore
-use std::error::Error;
 use std::fs::File;
 use std::io::prelude::*;
 use std::path::Path;
@@ -18,24 +17,19 @@ fn main() {
 
     // Open the path in read-only mode, returns `io::Result<File>`
     let mut file = match File::open(&path) {
-        // The `description` method of `io::Error` returns a string that
-        // describes the error
-        Err(why) => panic!("couldn't open {}: {}", display,
-                                                   why.description()),
+        Err(why) => panic!("couldn't open {}: {}", display, why),
         Ok(file) => file,
     };
 
     // Read the file contents into a string, returns `io::Result<usize>`
     let mut s = String::new();
     match file.read_to_string(&mut s) {
-        Err(why) => panic!("couldn't read {}: {}", display,
-                                                   why.description()),
+        Err(why) => panic!("couldn't read {}: {}", display, why),
         Ok(_) => print!("{} contains:\n{}", display, s),
     }
 
     // `file` goes out of scope, and the "hello.txt" file gets closed
 }
-
 ```
 
 Here's the expected successful output:

src/std_misc/process/pipe.md

@@ -5,7 +5,6 @@ The `std::Child` struct represents a running child process, and exposes the
 process via pipes.
 
 ```rust,ignore
-use std::error::Error;
 use std::io::prelude::*;
 use std::process::{Command, Stdio};
 
@@ -18,7 +17,7 @@ fn main() {
                                 .stdin(Stdio::piped())
                                 .stdout(Stdio::piped())
                                 .spawn() {
-        Err(why) => panic!("couldn't spawn wc: {}", why.description()),
+        Err(why) => panic!("couldn't spawn wc: {}", why),
         Ok(process) => process,
     };
 
@@ -27,8 +26,7 @@ fn main() {
     // `stdin` has type `Option<ChildStdin>`, but since we know this instance
     // must have one, we can directly `unwrap` it.
     match process.stdin.unwrap().write_all(PANGRAM.as_bytes()) {
-        Err(why) => panic!("couldn't write to wc stdin: {}",
-                           why.description()),
+        Err(why) => panic!("couldn't write to wc stdin: {}", why),
         Ok(_) => println!("sent pangram to wc"),
     }
 
@@ -41,8 +39,7 @@ fn main() {
     // The `stdout` field also has type `Option<ChildStdout>` so must be unwrapped.
     let mut s = String::new();
     match process.stdout.unwrap().read_to_string(&mut s) {
-        Err(why) => panic!("couldn't read wc stdout: {}",
-                           why.description()),
+        Err(why) => panic!("couldn't read wc stdout: {}", why),
         Ok(_) => print!("wc responded with:\n{}", s),
     }
 }