diff --git a/doc/langref.html.in b/doc/langref.html.in
index 225b98303b48..829a6b745120 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -2180,16 +2180,20 @@ or
Unlike normal structs, {#syntax#}packed{#endsyntax#} structs have guaranteed in-memory layout:
- - Fields remain in the order declared, least to most significant.
+ - Fields are arranged in the order declared, from the least to the most significant bits of a backing integer.
- There is no padding between fields.
- - Zig supports arbitrary width {#link|Integers#} and although normally, integers with fewer
- than 8 bits will still use 1 byte of memory, in packed structs, they use
- exactly their bit width.
+
- The backing integer is subject to the same rules as any integer, including {#link|alignment|Alignment#},
+ having a maximum bit count of 65535, and the host endianness.
+ On a big endian system, the first declared field will have the highest memory address.
+ - The backing integer has the same bit count as the fields' total bit width.
+ - Field access and assignment can be understood as shorthand for bitshifts on the backing integer.
+ - Integers will use exactly as many bits as they have. For example, a {#syntax#}u5{#endsyntax#} will use 5 bits of the backing integer.
- {#syntax#}bool{#endsyntax#} fields use exactly 1 bit.
- An {#link|enum#} field uses exactly the bit width of its integer tag type.
- A {#link|packed union#} field uses exactly the bit width of the union field with
the largest bit width.
+ - Packed structs, when they themselves are within a packed struct, will only use as many bits as their backing integer.
- Packed structs support equality operators.
@@ -2200,8 +2204,7 @@ or
{#code|test_packed_structs.zig#}
- The backing integer is inferred from the fields' total bit width.
- Optionally, it can be explicitly provided and enforced at compile time:
+ The backing integer can be inferred or explicitly provided. When inferred it will be unsigned, and when explicitly provided, its bit count will be enforced at compile time:
{#code|test_missized_packed_struct.zig#}
@@ -2248,9 +2251,6 @@ or
{#code|test_packed_struct_equality.zig#}
- Using packed structs with {#link|volatile#} is problematic, and may be a compile error in the future.
- For details on this subscribe to
- this issue.
TODO update these docs with a recommendation on how to use packed structs with MMIO
(the use case for volatile packed structs) once this issue is resolved.
Don't worry, there will be a good solution for this use case in zig.