Auto merge of #30155 - steveklabnik:rollup, r=steveklabnik

- Successful merges: #30129, #30134, #30136, #30144, #30150, #30153, #30154
- Failed merges:

11 files changed, 54 insertions, 39 deletions

diff --git a/src/doc/book/documentation.md b/src/doc/book/documentation.md
index 80aed0d1ca7..0d0fd8cf1d0 100644
--- a/src/doc/book/documentation.md
+++ b/src/doc/book/documentation.md
@@ -213,8 +213,8 @@ Let's discuss our sample example documentation:
 ```
 
 You'll notice that you don't need a `fn main()` or anything here. `rustdoc` will
-automatically add a `main()` wrapper around your code, and in the right place.
-For example:
+automatically add a `main()` wrapper around your code, using heuristics to attempt
+to put it in the right place. For example:
 
 ```rust
 /// ```
@@ -242,11 +242,18 @@ Here's the full algorithm rustdoc uses to preprocess examples:
    `unused_attributes`, and `dead_code`. Small examples often trigger
    these lints.
 3. If the example does not contain `extern crate`, then `extern crate
-   <mycrate>;` is inserted.
-2. Finally, if the example does not contain `fn main`, the remainder of the
-   text is wrapped in `fn main() { your_code }`
-
-Sometimes, this isn't enough, though. For example, all of these code samples
+   <mycrate>;` is inserted (note the lack of `#[macro_use]`).
+4. Finally, if the example does not contain `fn main`, the remainder of the
+   text is wrapped in `fn main() { your_code }`.
+
+This generated `fn main` can be a problem! If you have `extern crate` or a `mod`
+statements in the example code that are referred to by `use` statements, they will
+fail to resolve unless you include at least `fn main() {}` to inhibit step 4.
+`#[macro_use] extern crate` also does not work except at the crate root, so when
+testing macros an explicit `main` is always required. It doesn't have to clutter
+up your docs, though -- keep reading!
+
+Sometimes this algorithm isn't enough, though. For example, all of these code samples
 with `///` we've been talking about? The raw text:
 
 ```text
@@ -370,8 +377,8 @@ macro_rules! panic_unless {
 
 You’ll note three things: we need to add our own `extern crate` line, so that
 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.
+`main()` as well (for reasons discussed above). 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,
diff --git a/src/doc/book/guessing-game.md b/src/doc/book/guessing-game.md
index 6a513fb2c59..8cb00f26ba5 100644
--- a/src/doc/book/guessing-game.md
+++ b/src/doc/book/guessing-game.md
@@ -357,9 +357,13 @@ Cargo uses the dependencies section to know what dependencies on external
 crates you have, and what versions you require. In this case, we’ve specified version `0.3.0`,
 which Cargo understands to be any release that’s compatible with this specific version.
 Cargo understands [Semantic Versioning][semver], which is a standard for writing version
-numbers. If we wanted to use only `0.3.0` exactly, we could use `=0.3.0`. If we
-wanted to use the latest version we could use `*`; We could use a range of
-versions. [Cargo’s documentation][cargodoc] contains more details.
+numbers. A bare number like above is actually shorthand for `^0.3.0`,
+meaning "anything compatible with 0.3.0".
+If we wanted to use only `0.3.0` exactly, we could say `rand="=0.3.0"`
+(note the two equal signs).
+And if we wanted to use the latest version we could use `*`.
+We could also use a range of versions.
+[Cargo’s documentation][cargodoc] contains more details.
 
 [semver]: http://semver.org
 [cargodoc]: http://doc.crates.io/crates-io.html
@@ -521,11 +525,11 @@ Please input your guess.
 You guessed: 5
 ```
 
-Great! Next up: let’s compare our guess to the secret guess.
+Great! Next up: comparing our guess to the secret number.
 
 # Comparing guesses
 
-Now that we’ve got user input, let’s compare our guess to the random guess.
+Now that we’ve got user input, let’s compare our guess to the secret number.
 Here’s our next step, though it doesn’t quite compile yet:
 
 ```rust,ignore
@@ -775,7 +779,7 @@ fn main() {
 ```
 
 And try it out. But wait, didn’t we just add an infinite loop? Yup. Remember
-our discussion about `parse()`? If we give a non-number answer, we’ll `return`
+our discussion about `parse()`? If we give a non-number answer, we’ll `panic!`
 and quit. Observe:
 
 ```bash
diff --git a/src/librustc/middle/infer/region_inference/mod.rs b/src/librustc/middle/infer/region_inference/mod.rs
index dd95fc4cc0d..df620d4a04e 100644
--- a/src/librustc/middle/infer/region_inference/mod.rs
+++ b/src/librustc/middle/infer/region_inference/mod.rs
@@ -159,8 +159,8 @@ pub enum RegionResolutionError<'tcx> {
 /// like to indicate so to the user.
 /// For example, the following function
 /// ```
-/// struct Foo { bar: int }
-/// fn foo2<'a, 'b>(x: &'a Foo) -> &'b int {
+/// struct Foo { bar: isize }
+/// fn foo2<'a, 'b>(x: &'a Foo) -> &'b isize {
 ///    &x.bar
 /// }
 /// ```
diff --git a/src/librustc/middle/liveness.rs b/src/librustc/middle/liveness.rs
index 9b18b79d261..14c2e1f5aac 100644
--- a/src/librustc/middle/liveness.rs
+++ b/src/librustc/middle/liveness.rs
@@ -1583,7 +1583,7 @@ impl<'a, 'tcx> Liveness<'a, 'tcx> {
             let r = self.should_warn(var);
             if let Some(name) = r {
 
-                // annoying: for parameters in funcs like `fn(x: int)
+                // annoying: for parameters in funcs like `fn(x: isize)
                 // {ret}`, there is only one node, so asking about
                 // assigned_on_exit() is not meaningful.
                 let is_assigned = if ln == self.s.exit_ln {
diff --git a/src/librustc_borrowck/borrowck/check_loans.rs b/src/librustc_borrowck/borrowck/check_loans.rs
index f6bb51a26ad..b460c0ec4d0 100644
--- a/src/librustc_borrowck/borrowck/check_loans.rs
+++ b/src/librustc_borrowck/borrowck/check_loans.rs
@@ -718,8 +718,8 @@ impl<'a, 'tcx> CheckLoanCtxt<'a, 'tcx> {
     ///
     /// For example:
     ///
-    /// ```
-    /// let a: int;
+    /// ```ignore
+    /// let a: isize;
     /// a = 10; // ok, even though a is uninitialized
     ///
     /// struct Point { x: usize, y: usize }
diff --git a/src/librustc_borrowck/borrowck/gather_loans/mod.rs b/src/librustc_borrowck/borrowck/gather_loans/mod.rs
index 083cc972cca..f3addf381e0 100644
--- a/src/librustc_borrowck/borrowck/gather_loans/mod.rs
+++ b/src/librustc_borrowck/borrowck/gather_loans/mod.rs
@@ -486,7 +486,9 @@ impl<'a, 'tcx> GatherLoanCtxt<'a, 'tcx> {
         //! come about when variables of `&mut` type are re-borrowed,
         //! as in this example:
         //!
-        //!     fn counter<'a>(v: &'a mut Foo) -> &'a mut uint {
+        //!     struct Foo { counter: usize }
+        //!
+        //!     fn counter<'a>(v: &'a mut Foo) -> &'a mut usize {
         //!         &mut v.counter
         //!     }
         //!
diff --git a/src/librustc_trans/trans/debuginfo/doc.rs b/src/librustc_trans/trans/debuginfo/doc.rs
index a91619b2f84..c7d9e3de5a1 100644
--- a/src/librustc_trans/trans/debuginfo/doc.rs
+++ b/src/librustc_trans/trans/debuginfo/doc.rs
@@ -66,7 +66,7 @@
 //!
 //! ```
 //! struct List {
-//!     value: int,
+//!     value: isize,
 //!     tail: Option<Box<List>>,
 //! }
 //! ```
diff --git a/src/librustc_trans/trans/meth.rs b/src/librustc_trans/trans/meth.rs
index 8449d63015e..795a56b2dcf 100644
--- a/src/librustc_trans/trans/meth.rs
+++ b/src/librustc_trans/trans/meth.rs
@@ -456,7 +456,7 @@ fn trans_trait_callee_from_llval<'blk, 'tcx>(bcx: Block<'blk, 'tcx>,
 /// Generate a shim function that allows an object type like `SomeTrait` to
 /// implement the type `SomeTrait`. Imagine a trait definition:
 ///
-///    trait SomeTrait { fn get(&self) -> int; ... }
+///    trait SomeTrait { fn get(&self) -> isize; ... }
 ///
 /// And a generic bit of code:
 ///
@@ -468,7 +468,7 @@ fn trans_trait_callee_from_llval<'blk, 'tcx>(bcx: Block<'blk, 'tcx>,
 /// What is the value of `x` when `foo` is invoked with `T=SomeTrait`?
 /// The answer is that it is a shim function generated by this routine:
 ///
-///    fn shim(t: &SomeTrait) -> int {
+///    fn shim(t: &SomeTrait) -> isize {
 ///        // ... call t.get() virtually ...
 ///    }
 ///
diff --git a/src/librustc_typeck/check/regionck.rs b/src/librustc_typeck/check/regionck.rs
index 549824d22a4..4f897d91b07 100644
--- a/src/librustc_typeck/check/regionck.rs
+++ b/src/librustc_typeck/check/regionck.rs
@@ -59,7 +59,7 @@
 //! There are a number of troublesome scenarios in the tests
 //! `region-dependent-*.rs`, but here is one example:
 //!
-//!     struct Foo { i: int }
+//!     struct Foo { i: isize }
 //!     struct Bar { foo: Foo  }
 //!     fn get_i(x: &'a Bar) -> &'a int {
 //!        let foo = &x.foo; // Lifetime L1
@@ -233,8 +233,8 @@ impl<'a, 'tcx> Rcx<'a, 'tcx> {
     /// Consider this silly example:
     ///
     /// ```
-    /// fn borrow(x: &int) -> &int {x}
-    /// fn foo(x: @int) -> int {  // block: B
+    /// fn borrow(x: &int) -> &isize {x}
+    /// fn foo(x: @int) -> isize {  // block: B
     ///     let b = borrow(x);    // region: <R0>
     ///     *b
     /// }
@@ -243,7 +243,7 @@ impl<'a, 'tcx> Rcx<'a, 'tcx> {
     /// Here, the region of `b` will be `<R0>`.  `<R0>` is constrained to be some subregion of the
     /// block B and some superregion of the call.  If we forced it now, we'd choose the smaller
     /// region (the call).  But that would make the *b illegal.  Since we don't resolve, the type
-    /// of b will be `&<R0>.int` and then `*b` will require that `<R0>` be bigger than the let and
+    /// of b will be `&<R0>.isize` and then `*b` will require that `<R0>` be bigger than the let and
     /// the `*b` expression, so we will effectively resolve `<R0>` to be the block B.
     pub fn resolve_type(&self, unresolved_ty: Ty<'tcx>) -> Ty<'tcx> {
         self.fcx.infcx().resolve_type_vars_if_possible(&unresolved_ty)
diff --git a/src/librustc_typeck/variance.rs b/src/librustc_typeck/variance.rs
index c9035bdff71..910f3b713cf 100644
--- a/src/librustc_typeck/variance.rs
+++ b/src/librustc_typeck/variance.rs
@@ -172,14 +172,14 @@
 //!
 //! Now imagine that I have an implementation of `ConvertTo` for `Object`:
 //!
-//!     impl ConvertTo<int> for Object { ... }
+//!     impl ConvertTo<isize> for Object { ... }
 //!
 //! And I want to call `convertAll` on an array of strings. Suppose
 //! further that for whatever reason I specifically supply the value of
 //! `String` for the type parameter `T`:
 //!
 //!     let mut vector = vec!["string", ...];
-//!     convertAll::<int, String>(vector);
+//!     convertAll::<isize, String>(vector);
 //!
 //! Is this legal? To put another way, can we apply the `impl` for
 //! `Object` to the type `String`? The answer is yes, but to see why
@@ -190,7 +190,7 @@
 //! - It will then call the impl of `convertTo()` that is intended
 //!   for use with objects. This has the type:
 //!
-//!       fn(self: &Object) -> int
+//!       fn(self: &Object) -> isize
 //!
 //!   It is ok to provide a value for `self` of type `&String` because
 //!   `&String <: &Object`.
@@ -198,17 +198,17 @@
 //! OK, so intuitively we want this to be legal, so let's bring this back
 //! to variance and see whether we are computing the correct result. We
 //! must first figure out how to phrase the question "is an impl for
-//! `Object,int` usable where an impl for `String,int` is expected?"
+//! `Object,isize` usable where an impl for `String,isize` is expected?"
 //!
 //! Maybe it's helpful to think of a dictionary-passing implementation of
 //! type classes. In that case, `convertAll()` takes an implicit parameter
 //! representing the impl. In short, we *have* an impl of type:
 //!
-//!     V_O = ConvertTo<int> for Object
+//!     V_O = ConvertTo<isize> for Object
 //!
 //! and the function prototype expects an impl of type:
 //!
-//!     V_S = ConvertTo<int> for String
+//!     V_S = ConvertTo<isize> for String
 //!
 //! As with any argument, this is legal if the type of the value given
 //! (`V_O`) is a subtype of the type expected (`V_S`). So is `V_O <: V_S`?
@@ -217,7 +217,7 @@
 //! covariant, it means that:
 //!
 //!     V_O <: V_S iff
-//!         int <: int
+//!         isize <: isize
 //!         String <: Object
 //!
 //! These conditions are satisfied and so we are happy.
diff --git a/src/libstd/env.rs b/src/libstd/env.rs
index a63c90c4a91..760733872ea 100644
--- a/src/libstd/env.rs
+++ b/src/libstd/env.rs
@@ -671,9 +671,9 @@ pub mod consts {
     ///
     /// Some possible values:
     ///
-    /// - .so
-    /// - .dylib
-    /// - .dll
+    /// - so
+    /// - dylib
+    /// - dll
     #[stable(feature = "env", since = "1.0.0")]
     pub const DLL_EXTENSION: &'static str = super::os::DLL_EXTENSION;
 
@@ -682,7 +682,9 @@ pub mod consts {
     ///
     /// Some possible values:
     ///
-    /// - exe
+    /// - .exe
+    /// - .nexe
+    /// - .pexe
     /// - `""` (an empty string)
     #[stable(feature = "env", since = "1.0.0")]
     pub const EXE_SUFFIX: &'static str = super::os::EXE_SUFFIX;