Document repr packed(N).

src/type-layout.md

@@ -110,16 +110,18 @@ Closures have no layout guarantees.
 ## Representations
 
 All user-defined composite types (`struct`s, `enum`s, and `union`s) have a
-*representation* that specifies what the layout is for the type.
+*representation* that specifies what the layout is for the type. The possible
+representations for a type are:
 
-The possible representations for a type are the default representation, `C`,
-the primitive representations, `packed`, and `transparent`. Multiple
-representations can be applied to a single type.
+- [Default]
+- [`C`]
+- The [primitive representations]
+- [`transparent`]
 
 The representation of a type can be changed by applying the `repr` attribute
 to it. The following example shows a struct with a `C` representation.
 
-```
+```rust
 #[repr(C)]
 struct ThreeInts {
     first: i16,
@@ -128,14 +130,37 @@ struct ThreeInts {
 }
 ```
 
+The alignment may be raised or lowered with the `align` and `packed` modifiers
+respectively. They alter the representation specified in the attribute.
+If no representation is specified, the default one is altered.
+
+```rust
+// Default representation, alignment lowered to 2.
+#[repr(packed(2))]
+struct PackedStruct {
+    first: i16,
+    second: i8,
+    third: i32
+}
+
+// C representation, alignment raised to 8
+#[repr(C, align(8))]
+struct AlignedStruct {
+    first: i16,
+    second: i8,
+    third: i32
+}
+```
+
 > Note: As a consequence of the representation being an attribute on the item,
 > the representation does not depend on generic parameters. Any two types with
 > the same name have the same representation. For example, `Foo<Bar>` and
 > `Foo<Baz>` both have the same representation.
 
-The representation of a type does not change the layout of its fields. For
-example, a struct with a `C` representation that contains a struct `Inner` with
-the default representation will not change the layout of Inner.
+The representation of a type can change the padding between fields, but does
+not change the layout of the fields themselves. For example, a struct with a
+`C` representation that contains a struct `Inner` with the default
+representation will not change the layout of `Inner`.
 
 ### The Default Representation
 
@@ -148,7 +173,7 @@ There are no guarantees of data layout made by this representation.
 
 The `C` representation is designed for dual purposes. One purpose is for
 creating types that are interoperable with the C Language. The second purpose is
-to create types that you can soundly performing operations that rely on data
+to create types that you can soundly perform operations on that rely on data
 layout such as reinterpreting values as a different type.
 
 Because of this dual purpose, it is possible to create types that are not useful
@@ -205,7 +230,7 @@ The union will have a size of the maximum size of all of its fields rounded to
 its alignment, and an alignment of the maximum alignment of all of its fields.
 These maximums may come from different fields.
 
-```
+```rust
 #[repr(C)]
 union Union {
     f1: u16,
@@ -274,28 +299,28 @@ For all other enumerations, the layout is unspecified.
 
 Likewise, combining two primitive representations together is unspecified.
 
-### The `align` Representation
-
-The `align` representation can be used on `struct`s and `union`s to raise the
-alignment of the type to a given value.
-
-Alignment is specified as a parameter in the form of `#[repr(align(x))]`. The
-alignment value must be a power of two of type `u32`. The `align` representation
-can raise the alignment of a type to be greater than it's primitive alignment,
-it cannot lower the alignment of a type.
+### The alignment modifiers
 
-The `align` and `packed` representations cannot be applied on the same type and
-a `packed` type cannot transitively contain another `align`ed type.
+The `align` and `packed` modifiers can be used to respectively raise or lower
+the alignment of `struct`s and `union`s. `packed` may also alter the padding
+between fields.
 
-### The `packed` Representation
+The alignment is specified as an integer parameter in the form of
+`#[repr(align(x))]` or `#[repr(packed(x))]`. The alignment value must be a
+power of two from 1 up to 2<sup>29</sup>. For `packed`, if no value is given,
+as in `#[repr(packed)]`, then the value is 1.
 
-The `packed` representation can only be used on `struct`s and `union`s.
+For `align`, if the specified alignment is less than the alignment of the type
+without the `align` modifier, then the alignment is unaffected.
 
-It modifies the representation (either the default or `C`) by removing any
-padding bytes and forcing the alignment of the type to `1`.
+For `packed`, if the specified alignment is greater than the type's alignment
+without the `packed` modifier, then the alignment and layout is unaffected.
+The alignments of each field, for the purpose of positioning fields, is the
+smaller of the specified alignment and the alignment of the field's type.
 
-The `align` and `packed` representations cannot be applied on the same type and
-a `packed` type cannot transitively contain another `align`ed type.
+The `align` and `packed` modifiers cannot be applied on the same type and a
+`packed` type cannot transitively contain another `align`ed type. `align` and
+`packed` may only be applied to the [default] and [`C`] representations.
 
 <div class="warning">
 
@@ -333,3 +358,7 @@ used with any other representation.
 [undefined behavior]: behavior-considered-undefined.html
 [27060]: https://github.com/rust-lang/rust/issues/27060
 [`PhantomData<T>`]: special-types-and-traits.html#phantomdatat
+[Default]: #the-default-representation
+[`C`]: #the-c-representation
+[primitive representations]: #primitive-representations
+[`transparent`]: #the-transparent-representation