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] 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 cbfaac8c4b3..51b21ce572a 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 {