Rollup of 6 pull requests

src/doc/README.md

@@ -29,4 +29,4 @@ rustdoc reference.md
 An overview of how to use the `rustdoc` command is available [in the docs][1].
 Further details are available from the command line by with `rustdoc --help`.
 
-[1]: https://github.com/rust-lang/rust/blob/master/src/doc/trpl/documentation.md
+[1]: https://github.com/rust-lang/rust/blob/master/src/doc/book/documentation.md

src/doc/book/casting-between-types.md

@@ -14,18 +14,24 @@ Coercion occurs in `let`, `const`, and `static` statements; in
 function call arguments; in field values in struct initialization; and in a
 function result.
 
-The main cases of coercion are:
+The most common case of coercion is removing mutability from a reference:
 
  * `&mut T` to `&T`
+
+An analogous conversion is to remove mutability from a
+[raw pointer](raw-pointers.md):
 
  * `*mut T` to `*const T`
+
+References can also be coerced to raw pointers:
 
  * `&T` to `*const T`
 
  * `&mut T` to `*mut T`
-
- * A custom coercion using [`Deref`](deref-coercions.md)
-
+
+Custom coercions may be defined using [`Deref`](deref-coercions.md).
+
+Coercion is transitive.
 
 # `as`
 
@@ -49,13 +55,6 @@ expression, `e as U2` is not necessarily so (in fact it will only be valid if
 
 A cast `e as U` is valid if `e` has type `T` and `T` *coerces* to `U`.
 
-For example:
-
-```rust
-let a = "hello";
-let b = a as String;
-```
-
 ## Numeric casts
 
 A cast `e as U` is also valid in any of the following cases:
@@ -71,6 +70,7 @@ For example
 ```rust
 let one = true as u8;
 let at_sign = 64 as char;
+let two_hundred = -56i8 as u8;
 ```
 
 The semantics of numeric casts are:
@@ -101,9 +101,14 @@ The semantics of numeric casts are:
 
 ## Pointer casts
 
-Perhaps surprisingly, it is safe to cast pointers to and from integers, and
-to cast between pointers to different types subject to some constraints. It
-is only unsafe to dereference the pointer.
+Perhaps surprisingly, it is safe to cast [raw pointers](raw-pointers.md) to and
+from integers, and to cast between pointers to different types subject to
+some constraints. It is only unsafe to dereference the pointer:
+
+```rust
+let a = 300 as *const char; // a pointer to location 300
+let b = a as u32;
+```
 
 `e as U` is a valid pointer cast in any of the following cases:
 

src/doc/book/the-stack-and-the-heap.md

@@ -109,7 +109,7 @@ stack frame. It grows upward, the more functions we call.
 
 There are some important things we have to take note of here. The numbers 0, 1,
 and 2 are all solely for illustrative purposes, and bear no relationship to the
-actual numbers the computer will actually use. In particular, the series of
+address values the computer will use in reality. In particular, the series of
 addresses are in reality going to be separated by some number of bytes that
 separate each address, and that separation may even exceed the size of the
 value being stored.
@@ -464,7 +464,7 @@ At the end of `bar()`, it calls `baz()`:
 | (2<sup>30</sup>) - 2 |      | 5                      |
 | ...                  | ...  | ...                    |
 | 12                   | g    | 100                    |
-| 11                   | f    | → 9                    |
+| 11                   | f    | → (2<sup>30</sup>) - 2 |
 | 10                   | e    | → 9                    |
 | 9                    | d    | → (2<sup>30</sup>) - 2 |
 | 8                    | c    | 5                      |

src/libcollections/string.rs

@@ -1190,10 +1190,28 @@ impl PartialEq for ParseError {
 #[stable(feature = "str_parse_error", since = "1.5.0")]
 impl Eq for ParseError {}
 
-/// A generic trait for converting a value to a string
+/// A trait for converting a value to a `String`.
+///
+/// This trait is automatically implemented for any type which implements the
+/// [`Display`] trait. As such, `ToString` shouldn't be implemented directly:
+/// [`Display`] should be implemented instead, and you get the `ToString`
+/// implementation for free.
+///
+/// [`Display`]: ../fmt/trait.Display.html
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait ToString {
-    /// Converts the value of `self` to an owned string
+    /// Converts the given value to a `String`.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// let i = 5;
+    /// let five = String::from("5");
+    ///
+    /// assert_eq!(five, i.to_string());
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     fn to_string(&self) -> String;
 }