From 3c46e36d39cc0f833075e59936cf96a60f6348e4 Mon Sep 17 00:00:00 2001
From: Alexis Bourget <alexis.bourget@gmail.com>
Date: Mon, 22 Jun 2020 16:27:23 +0200
Subject: [PATCH 1/2] Document the mut keyword

---
 src/libstd/keyword_docs.rs | 45 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 43 insertions(+), 2 deletions(-)

diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs
index a4996d9eee810..7d54f9ed2d20f 100644
--- a/src/libstd/keyword_docs.rs
+++ b/src/libstd/keyword_docs.rs
@@ -967,9 +967,50 @@ mod move_keyword {}
 //
 /// A mutable binding, reference, or pointer.
 ///
-/// The documentation for this keyword is [not yet complete]. Pull requests welcome!
+/// `mut` can be used in several situations. The first is mutable bindings,
+/// which can be used anywhere you can bind a value to a variable name. Some
+/// examples:
 ///
-/// [not yet complete]: https://github.com/rust-lang/rust/issues/34601
+/// ```
+/// // A mutable binding in the parameter list of a function.
+/// fn foo(mut x: u8, y: u8) -> u8 {
+///     x += y;
+///     x
+/// }
+///
+/// // A mutable binding for a variable.
+/// let mut a = 5;
+/// a = 6;
+///
+/// assert_eq!(foo(3, 4), 7);
+/// assert_eq!(a, 6);
+/// ```
+///
+/// The second is references. They can be created from `mut` bindings and must
+/// be unique: no other binding can have a mutable reference, nor a simple
+/// reference.
+///
+/// ```
+/// // Taking a mutable reference.
+/// fn push_two(v: &mut Vec<u8>) {
+///     v.push(2);
+/// }
+///
+/// // You cannot take a mutable reference to a non-mutable variable.
+/// let mut v = vec![0, 1];
+/// // Passing a mutable reference.
+/// push_two(&mut v);
+///
+/// assert_eq!(v, vec![0, 1, 2]);
+/// ```
+///
+/// Mutable pointers work much like mutable references, with the added
+/// possibility of being nul. The syntax is `*mut Type`.
+///
+/// You can find more information on mutable references and pointers in the
+/// [Reference].
+///
+/// [Reference]: ../reference/types/pointer.html#mutable-references-mut
 mod mut_keyword {}
 
 #[doc(keyword = "pub")]

From 3d09017477e562d44cb90fca1a4a38c75f664f2d Mon Sep 17 00:00:00 2001
From: Alexis Bourget <alexis.bourget@gmail.com>
Date: Thu, 25 Jun 2020 10:05:30 +0200
Subject: [PATCH 2/2] Add a compile fail example, binding -> variable, apply
 suggestions

---
 src/libstd/keyword_docs.rs | 35 ++++++++++++++++++++++-------------
 1 file changed, 22 insertions(+), 13 deletions(-)

diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs
index 7d54f9ed2d20f..32fa0da3e2925 100644
--- a/src/libstd/keyword_docs.rs
+++ b/src/libstd/keyword_docs.rs
@@ -965,20 +965,21 @@ mod move_keyword {}
 
 #[doc(keyword = "mut")]
 //
-/// A mutable binding, reference, or pointer.
+/// A mutable variable, reference, or pointer.
 ///
-/// `mut` can be used in several situations. The first is mutable bindings,
+/// `mut` can be used in several situations. The first is mutable variables,
 /// which can be used anywhere you can bind a value to a variable name. Some
 /// examples:
 ///
-/// ```
-/// // A mutable binding in the parameter list of a function.
+/// ```rust
+/// // A mutable variable in the parameter list of a function.
 /// fn foo(mut x: u8, y: u8) -> u8 {
 ///     x += y;
 ///     x
 /// }
 ///
-/// // A mutable binding for a variable.
+/// // Modifying a mutable variable.
+/// # #[allow(unused_assignments)]
 /// let mut a = 5;
 /// a = 6;
 ///
@@ -986,17 +987,17 @@ mod move_keyword {}
 /// assert_eq!(a, 6);
 /// ```
 ///
-/// The second is references. They can be created from `mut` bindings and must
-/// be unique: no other binding can have a mutable reference, nor a simple
-/// reference.
+/// The second is mutable references. They can be created from `mut` variables
+/// and must be unique: no other variables can have a mutable reference, nor a
+/// shared reference.
 ///
-/// ```
+/// ```rust
 /// // Taking a mutable reference.
 /// fn push_two(v: &mut Vec<u8>) {
 ///     v.push(2);
 /// }
 ///
-/// // You cannot take a mutable reference to a non-mutable variable.
+/// // A mutable reference cannot be taken to a non-mutable variable.
 /// let mut v = vec![0, 1];
 /// // Passing a mutable reference.
 /// push_two(&mut v);
@@ -1004,10 +1005,18 @@ mod move_keyword {}
 /// assert_eq!(v, vec![0, 1, 2]);
 /// ```
 ///
-/// Mutable pointers work much like mutable references, with the added
-/// possibility of being nul. The syntax is `*mut Type`.
+/// ```rust,compile_fail,E0502
+/// let mut v = vec![0, 1];
+/// let mut_ref_v = &mut v;
+/// ##[allow(unused)]
+/// let ref_v = &v;
+/// mut_ref_v.push(2);
+/// ```
+///
+/// Mutable raw pointers work much like mutable references, with the added
+/// possibility of not pointing to a valid object. The syntax is `*mut Type`.
 ///
-/// You can find more information on mutable references and pointers in the
+/// More information on mutable references and pointers can be found in```
 /// [Reference].
 ///
 /// [Reference]: ../reference/types/pointer.html#mutable-references-mut