From 2e21af2859854668448ac96f335986a19011e571 Mon Sep 17 00:00:00 2001
From: Alexis Bourget <alexis.bourget@gmail.com>
Date: Mon, 29 Jun 2020 19:18:40 +0200
Subject: [PATCH 1/2] Document the union keyword

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

diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs
index d972cf6db18cf..cbfaac8c4b317 100644
--- a/src/libstd/keyword_docs.rs
+++ b/src/libstd/keyword_docs.rs
@@ -1624,8 +1624,71 @@ mod dyn_keyword {}
 //
 /// The [Rust equivalent of a C-style union][union].
 ///
-/// The documentation for this keyword is [not yet complete]. Pull requests welcome!
+/// A `union` looks like a [`struct`] in terms of declaration, but all of its
+/// fields exist simultaneously, superimposed over one another. For instance,
+/// if we wanted some bits in memory that we sometimes interpret as a `u32` and
+/// sometimes as an `f32`, we would write:
+///
+/// ```rust
+/// union IntOrFloat {
+///     i: u32,
+///     f: f32,
+/// }
+///
+/// let mut u = IntOrFloat { f: 1.0 };
+/// // Reading the fields of an union is always unsafe
+/// assert_eq!(unsafe { u.i }, 1065353216);
+/// // Updating through any of the field will modify all of them
+/// u.i = 1073741824;
+/// assert_eq!(unsafe { u.f }, 2.0);
+/// ```
+///
+/// # Matching on unions
+///
+/// It is possible to use pattern matching on `union`s. A single field name must
+/// be used and it must match the name of one of the `union`'s field.
+///
+/// ```rust
+/// union IntOrFloat {
+///     i: u32,
+///     f: f32,
+/// }
+///
+/// let u = IntOrFloat { f: 1.0 };
+///
+/// unsafe {
+///     match u {
+///         IntOrFloat { i: 10 } => println!("Found exactly ten !"),
+///         // The field name is used to deduce the type
+///         IntOrFloat { f } => println!("Found f = {} !", f),
+///     }
+/// }
+/// ```
+///
+/// # References to union fields
+///
+/// All fields in a union are all at the same place in memory which means
+/// borrowing one borrows all of them, for the same duration:
+///
+/// ```rust,compile_fail,E0502
+/// union IntOrFloat {
+///     i: u32,
+///     f: f32,
+/// }
 ///
+/// let mut u = IntOrFloat { f: 1.0 };
+///
+/// let f = unsafe { &u.f };
+/// // This will not compile because the field has already been borrowed, even
+/// // if only immutably
+/// let i = unsafe { &mut u.i };
+///
+/// *i = 10;
+/// println!("f = {} and i = {}", f, i);
+/// ```
+///
+/// See the [Reference][union] for more informations on `union`s.
+///
+/// [`struct`]: keyword.struct.html
 /// [union]: ../reference/items/unions.html
-/// [not yet complete]: https://github.com/rust-lang/rust/issues/34601
 mod union_keyword {}

From 614f7738ba65ac37f2dc61afa8c68fc3768fdffc Mon Sep 17 00:00:00 2001
From: Poliorcetics <poliorcetics@users.noreply.github.com>
Date: Tue, 30 Jun 2020 11:14:45 +0200
Subject: [PATCH 2/2] Clarify some parts by applying the suggestions from
 review

Co-authored-by: Josh Triplett <josh@joshtriplett.org>
---
 src/libstd/keyword_docs.rs | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs
index cbfaac8c4b317..51b21ce572a3f 100644
--- a/src/libstd/keyword_docs.rs
+++ b/src/libstd/keyword_docs.rs
@@ -1625,9 +1625,9 @@ mod dyn_keyword {}
 /// The [Rust equivalent of a C-style union][union].
 ///
 /// A `union` looks like a [`struct`] in terms of declaration, but all of its
-/// fields exist simultaneously, superimposed over one another. For instance,
+/// fields exist in the same memory, superimposed over one another. For instance,
 /// if we wanted some bits in memory that we sometimes interpret as a `u32` and
-/// sometimes as an `f32`, we would write:
+/// sometimes as an `f32`, we could write:
 ///
 /// ```rust
 /// union IntOrFloat {
@@ -1647,6 +1647,7 @@ mod dyn_keyword {}
 ///
 /// It is possible to use pattern matching on `union`s. A single field name must
 /// be used and it must match the name of one of the `union`'s field.
+/// Like reading from a `union`, pattern matching on a `union` requires `unsafe`.
 ///
 /// ```rust
 /// union IntOrFloat {
@@ -1658,8 +1659,8 @@ mod dyn_keyword {}
 ///
 /// unsafe {
 ///     match u {
-///         IntOrFloat { i: 10 } => println!("Found exactly ten !"),
-///         // The field name is used to deduce the type
+///         IntOrFloat { i: 10 } => println!("Found exactly ten!"),
+///         // Matching the field `f` provides an `f32`.
 ///         IntOrFloat { f } => println!("Found f = {} !", f),
 ///     }
 /// }
@@ -1667,8 +1668,8 @@ mod dyn_keyword {}
 ///
 /// # References to union fields
 ///
-/// All fields in a union are all at the same place in memory which means
-/// borrowing one borrows all of them, for the same duration:
+/// All fields in a `union` are all at the same place in memory which means
+/// borrowing one borrows the entire `union`, for the same lifetime:
 ///
 /// ```rust,compile_fail,E0502
 /// union IntOrFloat {