From b667ff7d6e27e6bbff4d775e8d4dd43804104e1e Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 19 Aug 2015 19:43:18 +0200 Subject: [PATCH 1/8] doc: improve transmute example a little --- src/libcore/intrinsics.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libcore/intrinsics.rs b/src/libcore/intrinsics.rs index 5cbca1ba4c68..998b07f1f916 100644 --- a/src/libcore/intrinsics.rs +++ b/src/libcore/intrinsics.rs @@ -247,8 +247,8 @@ extern "rust-intrinsic" { /// ``` /// use std::mem; /// - /// let v: &[u8] = unsafe { mem::transmute("L") }; - /// assert!(v == [76]); + /// let array: &[u8] = unsafe { mem::transmute("Rust") }; + /// assert_eq!(array, [82, 117, 115, 116]); /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn transmute(e: T) -> U; From 0eb33fb03f86f8888f6c5f2061d59d854321951c Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 19 Aug 2015 19:45:31 +0200 Subject: [PATCH 2/8] make these parameters follow idiom --- src/libcore/intrinsics.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcore/intrinsics.rs b/src/libcore/intrinsics.rs index 5cbca1ba4c68..25d281b6db5a 100644 --- a/src/libcore/intrinsics.rs +++ b/src/libcore/intrinsics.rs @@ -251,7 +251,7 @@ extern "rust-intrinsic" { /// assert!(v == [76]); /// ``` #[stable(feature = "rust1", since = "1.0.0")] - pub fn transmute(e: T) -> U; + pub fn transmute(e: T) -> U; /// Gives the address for the return value of the enclosing function. /// From a274a64669b669c6106bea76ffdb6d09ded655bd Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Thu, 20 Aug 2015 21:17:20 +0200 Subject: [PATCH 3/8] nomicon: use current syntax --- src/doc/nomicon/coercions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/nomicon/coercions.md b/src/doc/nomicon/coercions.md index 2e33a6729d1c..1d2897ce3bd1 100644 --- a/src/doc/nomicon/coercions.md +++ b/src/doc/nomicon/coercions.md @@ -22,7 +22,7 @@ Coercion is allowed between the following types: for all pointer types (including smart pointers like Box and Rc). Unsize is only implemented automatically, and enables the following transformations: -* `[T, ..n]` => `[T]` +* `[T; n]` => `[T]` * `T` => `Trait` where `T: Trait` * `Foo<..., T, ...>` => `Foo<..., U, ...>` where: * `T: Unsize` From 71d654a641d48dbd97da62a3571c19475ef59cc9 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Thu, 20 Aug 2015 21:37:12 +0200 Subject: [PATCH 4/8] nomicon: insert missing words --- src/doc/nomicon/safe-unsafe-meaning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/nomicon/safe-unsafe-meaning.md b/src/doc/nomicon/safe-unsafe-meaning.md index 2f15b7050e36..e9037b56ff9d 100644 --- a/src/doc/nomicon/safe-unsafe-meaning.md +++ b/src/doc/nomicon/safe-unsafe-meaning.md @@ -125,7 +125,7 @@ unsafe impl UnsafeOrd for MyType { But it's probably not the implementation you want. Rust has traditionally avoided making traits unsafe because it makes Unsafe -pervasive, which is not desirable. Send and Sync are unsafe is because thread +pervasive, which is not desirable. The reason Send and Sync are unsafe is because thread safety is a *fundamental property* that unsafe code cannot possibly hope to defend against in the same way it would defend against a bad Ord implementation. The only way to possibly defend against thread-unsafety would be to *not use From d112274fcb7175248a42c3b83382835710558cf4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kornel=20Lesin=CC=81ski?= Date: Thu, 20 Aug 2015 21:50:20 +0100 Subject: [PATCH 5/8] Use handle the same way in similarly structured examples --- src/doc/trpl/concurrency.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/doc/trpl/concurrency.md b/src/doc/trpl/concurrency.md index 17627da3513e..e00fe75013e2 100644 --- a/src/doc/trpl/concurrency.md +++ b/src/doc/trpl/concurrency.md @@ -343,12 +343,14 @@ threads as a simple isolation mechanism: ```rust use std::thread; -let result = thread::spawn(move || { +let handle = thread::spawn(move || { panic!("oops!"); -}).join(); +}); + +let result = handle.join(); assert!(result.is_err()); ``` -Our `Thread` gives us a `Result` back, which allows us to check if the thread +`Thread.join()` gives us a `Result` back, which allows us to check if the thread has panicked or not. From 8e6b9b8e93a2acb3afc046c87774878ac2dd86d6 Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Thu, 20 Aug 2015 18:41:24 -0400 Subject: [PATCH 6/8] emphasize that doctests don't run in bin crates --- src/doc/trpl/documentation.md | 12 ++++++------ src/doc/trpl/testing.md | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/doc/trpl/documentation.md b/src/doc/trpl/documentation.md index 556af6625c0f..7cbb9aefe5c5 100644 --- a/src/doc/trpl/documentation.md +++ b/src/doc/trpl/documentation.md @@ -196,10 +196,10 @@ This will highlight according to whatever language you're showing off. If you're just showing plain text, choose `text`. It's important to choose the correct annotation here, because `rustdoc` uses it -in an interesting way: It can be used to actually test your examples, so that -they don't get out of date. If you have some C code but `rustdoc` thinks it's -Rust because you left off the annotation, `rustdoc` will complain when trying to -generate the documentation. +in an interesting way: It can be used to actually test your examples in a +library crate, so that they don't get out of date. If you have some C code but +`rustdoc` thinks it's Rust because you left off the annotation, `rustdoc` will +complain when trying to generate the documentation. ## Documentation as tests @@ -377,8 +377,8 @@ $ rustdoc --test path/to/my/crate/root.rs $ cargo test ``` -That's right, `cargo test` tests embedded documentation too. However, -`cargo test` will not test binary crates, only library ones. This is +That's right, `cargo test` tests embedded documentation too. **However, +`cargo test` will not test binary crates, only library ones.** This is due to the way `rustdoc` works: it links against the library to be tested, but with a binary, there’s nothing to link to. diff --git a/src/doc/trpl/testing.md b/src/doc/trpl/testing.md index a5a0127031ae..cbf33febf876 100644 --- a/src/doc/trpl/testing.md +++ b/src/doc/trpl/testing.md @@ -355,8 +355,8 @@ Let's finally check out that third section: documentation tests. Nothing is better than documentation with examples. Nothing is worse than examples that don't actually work, because the code has changed since the documentation has been written. To this end, Rust supports automatically -running examples in your documentation. Here's a fleshed-out `src/lib.rs` -with examples: +running examples in your documentation (**note:** this only works in library +crates, not binary crates). Here's a fleshed-out `src/lib.rs` with examples: ```rust,ignore //! The `adder` crate provides functions that add numbers to other numbers. From bbe10c5c4f1c618af8cfed6d986e7dac060edea6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20=C4=BDach?= Date: Fri, 21 Aug 2015 17:10:46 +0100 Subject: [PATCH 7/8] fix spacing issue in trpl/documentation doc --- src/doc/trpl/documentation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/trpl/documentation.md b/src/doc/trpl/documentation.md index 556af6625c0f..bec1979365e0 100644 --- a/src/doc/trpl/documentation.md +++ b/src/doc/trpl/documentation.md @@ -73,8 +73,8 @@ 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 no -thing after that last comment. +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 From 59b69d4ae71109e561454692325d92494d56a1c0 Mon Sep 17 00:00:00 2001 From: Matt Brubeck Date: Fri, 21 Aug 2015 09:54:37 -0700 Subject: [PATCH 8/8] Include cfg(test) in the reference --- src/doc/reference.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/doc/reference.md b/src/doc/reference.md index b4dec8f1fef9..284fcf6aed0c 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -2073,6 +2073,7 @@ The following configurations must be defined by the implementation: * `target_pointer_width = "..."`. Target pointer width in bits. This is set to `"32"` for targets with 32-bit pointers, and likewise set to `"64"` for 64-bit pointers. +* `test`. Enabled when compiling the test harness (using the `--test` flag). * `unix`. See `target_family`. * `windows`. See `target_family`.