1 files changed, 30 insertions, 27 deletions

diff --git a/absl/base/casts.h b/absl/base/casts.h
index 83c69126..b16af233 100644
--- a/absl/base/casts.h
+++ b/absl/base/casts.h
@@ -105,47 +105,50 @@ constexpr To implicit_cast(typename absl::internal::identity_t<To> to) {
 
 // bit_cast()
 //
-// Performs a bitwise cast on a type without changing the underlying bit
-// representation of that type's value. The two types must be of the same size
-// and both types must be trivially copyable. As with most casts, use with
-// caution. A `bit_cast()` might be needed when you need to temporarily treat a
-// type as some other type, such as in the following cases:
-//
-//    * Serialization (casting temporarily to `char *` for those purposes is
-//      always allowed by the C++ standard)
-//    * Managing the individual bits of a type within mathematical operations
-//      that are not normally accessible through that type
-//    * Casting non-pointer types to pointer types (casting the other way is
-//      allowed by `reinterpret_cast()` but round-trips cannot occur the other
-//      way).
-//
-// Example:
+// Creates a value of the new type `Dest` whose representation is the same as
+// that of the argument, which is of (deduced) type `Source` (a "bitwise cast";
+// every bit in the value representation of the result is equal to the
+// corresponding bit in the object representation of the source). Source and
+// destination types must be of the same size, and both types must be trivially
+// copyable.
+//
+// As with most casts, use with caution. A `bit_cast()` might be needed when you
+// need to treat a value as the value of some other type, for example, to access
+// the individual bits of an object which are not normally accessible through
+// the object's type, such as for working with the binary representation of a
+// floating point value:
 //
 //   float f = 3.14159265358979;
 //   int i = bit_cast<int32_t>(f);
 //   // i = 0x40490fdb
 //
-// Casting non-pointer types to pointer types and then dereferencing them
-// traditionally produces undefined behavior.
+// Reinterpreting and accessing a value directly as a different type (as shown
+// below) usually results in undefined behavior.
 //
 // Example:
 //
 //   // WRONG
-//   float f = 3.14159265358979;            // WRONG
-//   int i = * reinterpret_cast<int*>(&f);  // WRONG
+//   float f = 3.14159265358979;
+//   int i = reinterpret_cast<int&>(f);    // Wrong
+//   int j = *reinterpret_cast<int*>(&f);  // Equally wrong
+//   int k = *bit_cast<int*>(&f);          // Equally wrong
+//
+// Reinterpret-casting results in undefined behavior according to the ISO C++
+// specification, section [basic.lval]. Roughly, this section says: if an object
+// in memory has one type, and a program accesses it with a different type, the
+// result is undefined behavior for most "different type".
 //
-// The address-casting method produces undefined behavior according to the ISO
-// C++ specification section [basic.lval]. Roughly, this section says: if an
-// object in memory has one type, and a program accesses it with a different
-// type, the result is undefined behavior for most values of "different type".
+// Using bit_cast on a pointer and then dereferencing it is no better than using
+// reinterpret_cast. You should only use bit_cast on the value itself.
 //
 // Such casting results in type punning: holding an object in memory of one type
 // and reading its bits back using a different type. A `bit_cast()` avoids this
-// issue by implementing its casts using `memcpy()`, which avoids introducing
-// this undefined behavior.
+// issue by copying the object representation to a new value, which avoids
+// introducing this undefined behavior (since the original value is never
+// accessed in the wrong way).
 //
-// NOTE: The requirements here are more strict than the bit_cast of standard
-// proposal p0476 due to the need for workarounds and lack of intrinsics.
+// NOTE: The requirements here are stricter than the bit_cast of standard
+// proposal P0476 due to the need for workarounds and lack of intrinsics.
 // Specifically, this implementation also requires `Dest` to be
 // default-constructible.
 template <