unions: call out field offset issues

Author: RalfJung

src/items/unions.md

@@ -39,11 +39,13 @@ let f = u.f1;
 
 Unions have no notion of an "active field". Instead, every union access just
 interprets the storage at the type of the field used for the access. Reading a
-union field reads the bits of the union at the field's type. It is the
-programmer's responsibility to make sure that the data is valid at that
-type. Failing to do so results in undefined behavior. For example, reading the
-value `3` at type `bool` is undefined behavior. Effectively, writing to and then
-reading from a union is analogous to a [`transmute`] from the type used for
+union field reads the bits of the union at the field's type. Fields might have a
+non-zero offset (except when `#[repr(C)]` is used); in that case the bits
+starting at the offset of the fields are read. It is the programmer's
+responsibility to make sure that the data is valid at that type. Failing to do
+so results in undefined behavior. For example, reading the value `3` at type
+`bool` is undefined behavior. Effectively, writing to and then reading from a
+`#[repr(C)]` union is analogous to a [`transmute`] from the type used for
 writing to the type used for reading.
 
 Consequently, all reads of union fields have to be placed in `unsafe` blocks:

src/types/union.md

@@ -1,15 +1,16 @@
 # Union types
 
 A *union type* is a nominal, heterogeneous C-like union, denoted by the name of
-a [`union` item].
+a [`union` item][item].
 
-A union access transmutes the content of the union to the type of the accessed
+Unions have no notion of an "active field". Instead, every union access
+transmutes parts of the content of the union to the type of the accessed
 field. Since transmutes can cause unexpected or undefined behaviour, `unsafe` is
 required to read from a union field or to write to a field that doesn't
-implement [`Copy`].
+implement [`Copy`]. See the [item] documentation for further details.
 
 The memory layout of a `union` is undefined by default, but the `#[repr(...)]`
 attribute can be used to fix a layout.
 
 [`Copy`]: special-types-and-traits.html#copy
-[`union` item]: items/unions.html
+[item]: items/unions.html