Auto merge of #33742 - Manishearth:rollup, r=Manishearth

Rollup of 10 pull requests

- Successful merges: #33353, #33611, #33696, #33698, #33705, #33708, #33712, #33720, #33721, #33730
- Failed merges:

Author: bors

src/doc/book/advanced-linking.md

@@ -12,7 +12,7 @@ the `link_args` attribute. This attribute is applied to `extern` blocks and
 specifies raw flags which need to get passed to the linker when producing an
 artifact. An example usage would be:
 
-``` no_run
+```rust,no_run
 #![feature(link_args)]
 
 #[link_args = "-foo -bar -baz"]
@@ -52,7 +52,7 @@ By default, all Rust programs on Linux will link to the system `libc` along with
 a number of other libraries. Let's look at an example on a 64-bit Linux machine
 with GCC and `glibc` (by far the most common `libc` on Linux):
 
-``` text
+```text
 $ cat example.rs
 fn main() {}
 $ rustc example.rs

src/doc/book/closures.md

@@ -319,6 +319,53 @@ assert_eq!(3, answer);
 Now we take a trait object, a `&Fn`. And we have to make a reference
 to our closure when we pass it to `call_with_one`, so we use `&||`.
 
+A quick note about closures that use explicit lifetimes. Sometimes you might have a closure
+that takes a reference like so:
+
+```
+fn call_with_ref<F>(some_closure:F) -> i32
+    where F: Fn(&i32) -> i32 {
+
+    let mut value = 0;
+    some_closure(&value)
+}
+```
+
+Normally you can specify the lifetime of the parameter to our closure. We
+could annotate it on the function declaration:
+
+```ignore
+fn call_with_ref<'a, F>(some_closure:F) -> i32 
+    where F: Fn(&'a 32) -> i32 {
+```
+
+However this presents a problem with in our case. When you specify the explict
+lifetime on a function it binds that lifetime to the *entire* scope of the function
+instead of just the invocation scope of our closure. This means that the borrow checker
+will see a mutable reference in the same lifetime as our immutable reference and fail
+to compile.
+
+In order to say that we only need the lifetime to be valid for the invocation scope
+of the closure we can use Higher-Ranked Trait Bounds with the `for<...>` syntax:
+
+```ignore
+fn call_with_ref<F>(some_closure:F) -> i32
+    where F: for<'a> Fn(&'a 32) -> i32 {
+```
+
+This lets the Rust compiler find the minimum lifetime to invoke our closure and 
+satisfy the borrow checker's rules. Our function then compiles and excutes as we
+expect.
+
+```
+fn call_with_ref<F>(some_closure:F) -> i32
+    where F: for<'a> Fn(&'a i32) -> i32 {
+
+    let mut value = 0;
+    some_closure(&value)
+}
+```
+
 # Function pointers and closures
 
 A function pointer is kind of like a closure that has no environment. As such,
@@ -344,7 +391,7 @@ assert_eq!(2, answer);
 In this example, we don’t strictly need the intermediate variable `f`,
 the name of the function works just fine too:
 
-```ignore
+```rust,ignore
 let answer = call_with_one(&add_one);
 ```
 

src/doc/book/compiler-plugins.md

@@ -37,7 +37,7 @@ Let's write a plugin
 [`roman_numerals.rs`](https://github.com/rust-lang/rust/tree/master/src/test/auxiliary/roman_numerals.rs)
 that implements Roman numeral integer literals.
 
-```ignore
+```rust,ignore
 #![crate_type="dylib"]
 #![feature(plugin_registrar, rustc_private)]
 
@@ -102,7 +102,7 @@ pub fn plugin_registrar(reg: &mut Registry) {
 
 Then we can use `rn!()` like any other macro:
 
-```ignore
+```rust,ignore
 #![feature(plugin)]
 #![plugin(roman_numerals)]
 
@@ -132,7 +132,7 @@ Some of the [macro debugging tips](macros.html#debugging-macro-code) are applica
 You can use `syntax::parse` to turn token trees into
 higher-level syntax elements like expressions:
 
-```ignore
+```rust,ignore
 fn expand_foo(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree])
         -> Box<MacResult+'static> {
 
@@ -169,7 +169,7 @@ infrastructure](../reference.html#lint-check-attributes) with additional checks
 code style, safety, etc. Now let's write a plugin [`lint_plugin_test.rs`](https://github.com/rust-lang/rust/blob/master/src/test/auxiliary/lint_plugin_test.rs)
 that warns about any item named `lintme`.
 
-```ignore
+```rust,ignore
 #![feature(plugin_registrar)]
 #![feature(box_syntax, rustc_private)]
 
@@ -211,7 +211,7 @@ pub fn plugin_registrar(reg: &mut Registry) {
 
 Then code like
 
-```ignore
+```rust,ignore
 #![plugin(lint_plugin_test)]
 
 fn lintme() { }

src/doc/book/concurrency.md

@@ -165,7 +165,7 @@ concurrency bugs.
 As an example, here is a Rust program that would have a data race in many
 languages. It will not compile:
 
-```ignore
+```rust,ignore
 use std::thread;
 use std::time::Duration;
 
@@ -204,7 +204,7 @@ Calling `clone()` on an `Rc<T>` will return a new owned reference and bump the
 internal reference count. We create one of these for each thread:
 
 
-```ignore
+```rust,ignore
 use std::thread;
 use std::time::Duration;
 use std::rc::Rc;
@@ -250,7 +250,7 @@ In essence, `Arc<T>` is a type that lets us share ownership of data _across
 threads_.
 
 
-```ignore
+```rust,ignore
 use std::thread;
 use std::sync::Arc;
 use std::time::Duration;
@@ -336,7 +336,7 @@ The lock "release" here is implicit; when the result of the lock (in this case,
 Note that [`lock`](../std/sync/struct.Mutex.html#method.lock) method of
 [`Mutex`](../std/sync/struct.Mutex.html) has this signature:
 
-```ignore
+```rust,ignore
 fn lock(&self) -> LockResult<MutexGuard<T>>
 ```
 

src/doc/book/documentation.md

@@ -362,7 +362,7 @@ Here’s an example of documenting a macro:
 /// # }
 /// ```
 ///
-/// ```should_panic
+/// ```rust,should_panic
 /// # #[macro_use] extern crate foo;
 /// # fn main() {
 /// panic_unless!(true == false, “I’m broken.”);
@@ -429,7 +429,7 @@ There are a few more annotations that are useful to help `rustdoc` do the right
 thing when testing your code:
 
 ```rust
-/// ```ignore
+/// ```rust,ignore
 /// fn foo() {
 /// ```
 # fn foo() {}
@@ -441,7 +441,7 @@ with `text` if it's not code, or using `#`s to get a working example that
 only shows the part you care about.
 
 ```rust
-/// ```should_panic
+/// ```rust,should_panic
 /// assert!(false);
 /// ```
 # fn foo() {}
@@ -451,7 +451,7 @@ only shows the part you care about.
 not actually pass as a test.
 
 ```rust
-/// ```no_run
+/// ```rust,no_run
 /// loop {
 ///     println!("Hello, world");
 /// }
@@ -563,7 +563,7 @@ can be useful when changing some options, or when writing a macro.
 
 `rustdoc` will show the documentation for a public re-export in both places:
 
-```ignore
+```rust,ignore
 extern crate foo;
 
 pub use foo::bar;
@@ -575,7 +575,7 @@ documentation in both places.
 
 This behavior can be suppressed with `no_inline`:
 
-```ignore
+```rust,ignore
 extern crate foo;
 
 #[doc(no_inline)]

src/doc/book/ffi.md

@@ -28,7 +28,7 @@ and add `extern crate libc;` to your crate root.
 The following is a minimal example of calling a foreign function which will
 compile if snappy is installed:
 
-```no_run
+```rust,no_run
 # #![feature(libc)]
 extern crate libc;
 use libc::size_t;
@@ -62,7 +62,7 @@ keeping the binding correct at runtime.
 
 The `extern` block can be extended to cover the entire snappy API:
 
-```no_run
+```rust,no_run
 # #![feature(libc)]
 extern crate libc;
 use libc::{c_int, size_t};
@@ -209,7 +209,7 @@ A basic example is:
 
 Rust code:
 
-```no_run
+```rust,no_run
 extern fn callback(a: i32) {
     println!("I'm called from C with value {0}", a);
 }
@@ -262,7 +262,7 @@ referenced Rust object.
 
 Rust code:
 
-```no_run
+```rust,no_run
 #[repr(C)]
 struct RustObject {
     a: i32,
@@ -406,7 +406,7 @@ Foreign APIs often export a global variable which could do something like track
 global state. In order to access these variables, you declare them in `extern`
 blocks with the `static` keyword:
 
-```no_run
+```rust,no_run
 # #![feature(libc)]
 extern crate libc;
 
@@ -425,7 +425,7 @@ Alternatively, you may need to alter global state provided by a foreign
 interface. To do this, statics can be declared with `mut` so we can mutate
 them.
 
-```no_run
+```rust,no_run
 # #![feature(libc)]
 extern crate libc;
 

src/doc/book/functions.md

@@ -134,7 +134,7 @@ x = y = 5
 In Rust, however, using `let` to introduce a binding is _not_ an expression. The
 following will produce a compile-time error:
 
-```ignore
+```rust,ignore
 let x = (let y = 5); // expected identifier, found keyword `let`
 ```
 
@@ -283,7 +283,7 @@ stack backtrace:
 
 A diverging function can be used as any type:
 
-```should_panic
+```rust,should_panic
 # fn diverges() -> ! {
 #    panic!("This function never returns!");
 # }

src/doc/book/inline-assembly.md

@@ -4,7 +4,7 @@ For extremely low-level manipulations and performance reasons, one
 might wish to control the CPU directly. Rust supports using inline
 assembly to do this via the `asm!` macro.
 
-```ignore
+```rust,ignore
 asm!(assembly template
    : output operands
    : input operands

src/doc/book/loops.md

@@ -74,7 +74,7 @@ for x in 0..10 {
 
 In slightly more abstract terms,
 
-```ignore
+```rust,ignore
 for var in expression {
     code
 }

src/doc/book/macros.md

@@ -78,7 +78,7 @@ macro_rules! vec {
 
 Whoa, that’s a lot of new syntax! Let’s break it down.
 
-```ignore
+```rust,ignore
 macro_rules! vec { ... }
 ```
 
@@ -92,7 +92,7 @@ syntax and serves to distinguish a macro from an ordinary function.
 The macro is defined through a series of rules, which are pattern-matching
 cases. Above, we had
 
-```ignore
+```rust,ignore
 ( $( $x:expr ),* ) => { ... };
 ```
 
@@ -112,7 +112,7 @@ separated by commas.
 Aside from the special matcher syntax, any Rust tokens that appear in a matcher
 must match exactly. For example,
 
-```rust
+```rust,ignore
 macro_rules! foo {
     (x => $e:expr) => (println!("mode X: {}", $e));
     (y => $e:expr) => (println!("mode Y: {}", $e));
@@ -147,7 +147,7 @@ The right-hand side of a macro rule is ordinary Rust syntax, for the most part.
 But we can splice in bits of syntax captured by the matcher. From the original
 example:
 
-```ignore
+```rust,ignore
 $(
     temp_vec.push($x);
 )*
@@ -165,7 +165,7 @@ within the repeated block.
 Another detail: the `vec!` macro has *two* pairs of braces on the right-hand
 side. They are often combined like so:
 
-```ignore
+```rust,ignore
 macro_rules! foo {
     () => {{
         ...

src/doc/book/mutability.md

@@ -55,6 +55,8 @@ fn foo(mut x: i32) {
 # }
 ```
 
+Note that here, the `x` is mutable, but not the `y`.
+
 [pattern]: patterns.html
 
 # Interior vs. Exterior Mutability

src/doc/book/operators-and-overloading.md

@@ -123,7 +123,7 @@ fn main() {
 For `HasArea` and `Square`, we declare a type parameter `T` and replace
 `f64` with it. The `impl` needs more involved modifications:
 
-```ignore
+```rust,ignore
 impl<T> HasArea<T> for Square<T>
         where T: Mul<Output=T> + Copy { ... }
 ```

src/doc/book/trait-objects.md

@@ -306,7 +306,7 @@ let y = TraitObject {
 Not every trait can be used to make a trait object. For example, vectors implement
 `Clone`, but if we try to make a trait object:
 
-```ignore
+```rust,ignore
 let v = vec![1, 2, 3];
 let o = &v as &Clone;
 ```

src/doc/book/traits.md

@@ -195,7 +195,7 @@ fn main() {
 `is_square()` needs to check that the sides are equal, so the sides must be of
 a type that implements the [`core::cmp::PartialEq`][PartialEq] trait:
 
-```ignore
+```rust,ignore
 impl<T: PartialEq> Rectangle<T> { ... }
 ```