auto merge of #16141 : alexcrichton/rust/rollup, r=alexcrichton

src/doc/complement-lang-faq.md

@@ -1,6 +1,5 @@
 % Language FAQ
 
-
 ## Are there any big programs written in it yet? I want to read big samples.
 
 There aren't many large programs yet. The Rust [compiler][rustc], 60,000+ lines at the time of writing, is written in Rust. As the oldest body of Rust code it has gone through many iterations of the language, and some parts are nicer to look at than others. It may not be the best code to learn from, but [borrowck] and [resolve] were written recently.
@@ -29,6 +28,18 @@ You may also be interested in browsing [GitHub's Rust][github-rust] page.
 
 [github-rust]: https://github.com/trending?l=rust
 
+## Is anyone using Rust in production?
+
+Currently, Rust is still pre-1.0, and so we don't recommend that you use Rust
+in production unless you know exactly what you're getting into.
+
+That said, there are two production deployments of Rust that we're aware of:
+
+* [OpenDNS](http://labs.opendns.com/2013/10/04/zeromq-helping-us-block-malicious-domains/)
+* [Skylight](http://skylight.io)
+
+Let the fact that this is an easily countable number be a warning.
+
 ## Does it run on Windows?
 
 Yes. All development happens in lock-step on all 3 target platforms. Using MinGW, not Cygwin. Note that the windows implementation currently has some limitations: in particular 64-bit build is [not fully supported yet][win64], and all executables created by rustc [depend on libgcc DLL at runtime][libgcc].

src/doc/guide-lifetimes.md

@@ -431,36 +431,6 @@ In any case, whatever the lifetime of `r` is, the pointer produced by
 field of a struct is valid as long as the struct is valid. Therefore,
 the compiler accepts the function `get_x()`.
 
-To emphasize this point, let’s look at a variation on the example, this
-time one that does not compile:
-
-~~~ {.ignore}
-struct Point {x: f64, y: f64}
-fn get_x_sh(p: &Point) -> &f64 {
-    &p.x // Error reported here
-}
-~~~
-
-Here, the function `get_x_sh()` takes a reference as input and
-returns a reference. As before, the lifetime of the reference
-that will be returned is a parameter (specified by the
-caller). That means that `get_x_sh()` promises to return a reference
-that is valid for as long as the caller would like: this is
-subtly different from the first example, which promised to return a
-pointer that was valid for as long as its pointer argument was valid.
-
-Within `get_x_sh()`, we see the expression `&p.x` which takes the
-address of a field of a Point. The presence of this expression
-implies that the compiler must guarantee that , so long as the
-resulting pointer is valid, the original Point won't be moved or changed.
-
-But recall that `get_x_sh()` also promised to
-return a pointer that was valid for as long as the caller wanted it to
-be. Clearly, `get_x_sh()` is not in a position to make both of these
-guarantees; in fact, it cannot guarantee that the pointer will remain
-valid at all once it returns, as the parameter `p` may or may not be
-live in the caller. Therefore, the compiler will report an error here.
-
 In general, if you borrow a struct or box to create a
 reference, it will only be valid within the function
 and cannot be returned. This is why the typical way to return references

src/doc/guide-pointers.md

@@ -578,12 +578,12 @@ fn main() {
 
 Notice we changed the signature of `add_one()` to request a mutable reference.
 
-# Best practices
+## Best practices
 
 Boxes are appropriate to use in two situations: Recursive data structures,
 and occasionally, when returning data.
 
-## Recursive data structures
+### Recursive data structures
 
 Sometimes, you need a recursive data structure. The simplest is known as a
 'cons list':
@@ -615,7 +615,7 @@ we don't know the size, and therefore, we need to heap allocate our list.
 Working with recursive or other unknown-sized data structures is the primary
 use-case for boxes.
 
-## Returning data
+### Returning data
 
 This is important enough to have its own section entirely. The TL;DR is this:
 you don't generally want to return pointers, even when you might in a language
@@ -733,18 +733,15 @@ This part is coming soon.
 
 Here's a quick rundown of Rust's pointer types:
 
-| Type         | Name                | Summary                                   |
-|--------------|---------------------|-------------------------------------------|
-| `&T`         | Reference           | Allows one or more references to read `T` |
-| `&mut T`     | Mutable Reference   | Allows a single reference to              |
-|              |                     | read and write `T`                        |
-| `Box<T>`     | Box                 | Heap allocated `T` with a single owner    |
-|              |                     | that may read and write `T`.              |
-| `Rc<T>`      | "arr cee" pointer   | Heap allocated `T` with many readers      |
-| `Arc<T>`     | Arc pointer         | Same as above, but safe sharing across    |
-|              |                     | threads                                   |
-| `*const T`   | Raw pointer         | Unsafe read access to `T`                 |
-| `*mut T`     | Mutable raw pointer | Unsafe read and write access to `T`       |
+| Type         | Name                | Summary                                                             |
+|--------------|---------------------|---------------------------------------------------------------------|
+| `&T`         | Reference           | Allows one or more references to read `T`                           |
+| `&mut T`     | Mutable Reference   | Allows a single reference to read and write `T`                     |
+| `Box<T>`     | Box                 | Heap allocated `T` with a single owner that may read and write `T`. |
+| `Rc<T>`      | "arr cee" pointer   | Heap allocated `T` with many readers                                |
+| `Arc<T>`     | Arc pointer         | Same as above, but safe sharing across threads                      |
+| `*const T`   | Raw pointer         | Unsafe read access to `T`                                           |
+| `*mut T`     | Mutable raw pointer | Unsafe read and write access to `T`                                 |
 
 # Related resources
 

src/doc/tutorial.md

@@ -1503,7 +1503,7 @@ reference. We also call this _borrowing_ the local variable
 `on_the_stack`, because we are creating an alias: that is, another
 route to the same data.
 
-Likewise, in the case of `owned_box`,
+Likewise, in the case of `on_the_heap`,
 the `&` operator is used in conjunction with the `*` operator
 to take a reference to the contents of the box.