Revise Result/Option guarantee docs

The notation used here (e.g. "transmute `t: T` to `Option<T>`") felt
maybe a bit heavy, in the context of the library documentation, so
let's elaborate this a bit.

Also, in the `Option` docs, we talk about this being true for "the
following types `T`", but it felt this caveat might get a bit lost in
the next sentence that talks about the valid transmutations, so let's
reiterate the caveat.

While we're touching the line, we can improve:

> The only difference is the implied semantics:

This sentence was a bit awkward due to the mismatched plurality and
not identifying the difference being spoken to.  We'll reword this to
make it more clear.

We'll wrap to 80, since the existing text and most of the doc comments
in these files are wrapped this way.

Author: traviscross

library/core/src/option.rs

@@ -118,10 +118,12 @@
 //!
 //! # Representation
 //!
-//! Rust guarantees to optimize the following types `T` such that
-//! [`Option<T>`] has the same size, alignment, and [function call ABI] as `T`.
-//! It is therefore sound to transmute `t: T` to `Option<T>` (which will produce `Some(t)`), and
-//! to transmute `Some(t): Option<T>` to `T` (which will produce `t`).
+//! Rust guarantees to optimize the following types `T` such that [`Option<T>`]
+//! has the same size, alignment, and [function call ABI] as `T`. It is
+//! therefore sound, when `T` is one of these types, to transmute a value `t` of
+//! type `T` to type `Option<T>` (producing the value `Some(t)`) and to
+//! transmute a value `Some(t)` of type `Option<T>` to type `T` (producing the
+//! value `t`).
 //!
 //! In some of these cases, Rust further guarantees the following:
 //! - `transmute::<_, Option<T>>([0u8; size_of::<T>()])` is sound and produces

library/core/src/result.rs

@@ -230,20 +230,25 @@
 //!
 //! # Representation
 //!
-//! In some cases, [`Result<T, E>`] comes with size, alignment, and ABI guarantees.
-//! Specifically, one of either the `T` or `E` type must be a type that qualifies for the `Option`
-//! [representation guarantees][opt-rep] (let's call that type `I`), and the *other* type
-//! is a zero-sized type with alignment 1 (a "1-ZST").
-//!
-//! If that is the case, then `Result<T, E>` has the same size, alignment, and [function call ABI]
-//! as `I` (and therefore, as `Option<I>`). If `I` is `T`, it is therefore sound to transmute `t: I`
-//! to `Result<T, E>` (which will produce `Ok(t)`), and to transmute `Ok(t): Result<T, E>` to `I`
-//! (which will produce `t`). If `I` is `E`, the same applies with `Ok` replaced by `Err`.
-//!
-//! For example, `NonZeroI32` qualifies for the `Option` representation guarantees, and `()` is a
-//! zero-sized type with alignment 1. This means that both `Result<NonZeroI32, ()>` and
-//! `Result<(), NonZeroI32>` have the same size, alignment, and ABI
-//! as `NonZeroI32` (and `Option<NonZeroI32>`). The only difference is the implied semantics:
+//! In some cases, [`Result<T, E>`] comes with size, alignment, and ABI
+//! guarantees. Specifically, one of either the `T` or `E` type must be a type
+//! that qualifies for the `Option` [representation guarantees][opt-rep] (let's
+//! call that type `I`), and the *other* type is a zero-sized type with
+//! alignment 1 (a "1-ZST").
+//!
+//! If that is the case, then `Result<T, E>` has the same size, alignment, and
+//! [function call ABI] as `I` (and therefore, as `Option<I>`). If `I` is `T`,
+//! it is therefore sound to transmute a value `t` of type `I` to type
+//! `Result<T, E>` (producing the value `Ok(t)`) and to transmute a value
+//! `Ok(t)` of type `Result<T, E>` to type `I` (producing the value `t`). If `I`
+//! is `E`, the same applies with `Ok` replaced by `Err`.
+//!
+//! For example, `NonZeroI32` qualifies for the `Option` representation
+//! guarantees and `()` is a zero-sized type with alignment 1. This means that
+//! both `Result<NonZeroI32, ()>` and `Result<(), NonZeroI32>` have the same
+//! size, alignment, and ABI as `NonZeroI32` (and `Option<NonZeroI32>`). The
+//! only difference between these is in the implied semantics:
+//!
 //! * `Option<NonZeroI32>` is "a non-zero i32 might be present"
 //! * `Result<NonZeroI32, ()>` is "a non-zero i32 success result, if any"
 //! * `Result<(), NonZeroI32>` is "a non-zero i32 error result, if any"