Reorder sections in bits to match the ordering in struct (#102)
* doc: reorder sections in bits to match the ordering in struct
* doc: add documentation about using struct to effectively create a union (#101)
diff --git a/doc/language-reference.md b/doc/language-reference.md
index 40da052..d9e132a 100644
--- a/doc/language-reference.md
+++ b/doc/language-reference.md
@@ -619,6 +619,20 @@
This can be useful as a way to group related fields together.
+#### Using `struct` to define a C-like `union`
+
+Emboss doesn't support C-like `union`s directly via built in type
+definitions. However, you can use Emboss's overlapping fields feature to
+effectively create a `union`:
+
+```
+struct Foo:
+ 0 [+1] UInt a
+ 0 [+2] UInt b
+ 0 [+4] UInt c
+```
+
+
#### Automatically-Generated Fields
A `struct` will have `$size_in_bytes`, `$max_size_in_bytes`, and
@@ -917,6 +931,61 @@
or writing a memory-mapped register space.
+#### Anonymous `bits`
+
+It is possible to use an anonymous `bits` definition directly in a `struct`;
+for example:
+
+```
+struct Message:
+ [$default byte_order: "BigEndian"]
+ 0 [+4] UInt message_length
+ 4 [+4] bits:
+ 0 [+1] Flag incoming
+ 1 [+1] Flag last_fragment
+ 2 [+4] UInt scale_factor
+ 31 [+1] Flag error
+```
+
+In this case, the fields of the `bits` will be treated as though they are fields
+of the outer struct.
+
+
+#### Inline `bits`
+
+Like `enum`s, it is also possible to define a named `bits` inline in a `struct`
+or `bits`. For example:
+
+```
+struct Message:
+ [$default byte_order: "BigEndian"]
+ 0 [+4] UInt message_length
+ 4 [+4] bits payload:
+ 0 [+1] Flag incoming
+ 1 [+1] Flag last_fragment
+ 2 [+4] UInt scale_factor
+ 31 [+1] Flag error
+```
+
+This is equivalent to:
+
+```
+struct Message:
+ [$default byte_order: "BigEndian"]
+
+ bits Payload:
+ 0 [+1] Flag incoming
+ 1 [+1] Flag last_fragment
+ 2 [+4] UInt scale_factor
+ 31 [+1] Flag error
+
+ 0 [+4] UInt message_length
+ 4 [+4] Payload payload
+```
+
+This can be useful as a way to group related fields together.
+
+
#### Automatically-Generated Fields
A `bits` will have `$size_in_bits`, `$max_size_in_bits`, and `$min_size_in_bits`
@@ -974,61 +1043,6 @@
`$min_size_in_bytes`.
-#### Anonymous `bits`
-
-It is possible to use an anonymous `bits` definition directly in a `struct`;
-for example:
-
-```
-struct Message:
- [$default byte_order: "BigEndian"]
- 0 [+4] UInt message_length
- 4 [+4] bits:
- 0 [+1] Flag incoming
- 1 [+1] Flag last_fragment
- 2 [+4] UInt scale_factor
- 31 [+1] Flag error
-```
-
-In this case, the fields of the `bits` will be treated as though they are fields
-of the outer struct.
-
-
-#### Inline `bits`
-
-Like `enum`s, it is also possible to define a named `bits` inline in a `struct`
-or `bits`. For example:
-
-```
-struct Message:
- [$default byte_order: "BigEndian"]
- 0 [+4] UInt message_length
- 4 [+4] bits payload:
- 0 [+1] Flag incoming
- 1 [+1] Flag last_fragment
- 2 [+4] UInt scale_factor
- 31 [+1] Flag error
-```
-
-This is equivalent to:
-
-```
-struct Message:
- [$default byte_order: "BigEndian"]
-
- bits Payload:
- 0 [+1] Flag incoming
- 1 [+1] Flag last_fragment
- 2 [+4] UInt scale_factor
- 31 [+1] Flag error
-
- 0 [+4] UInt message_length
- 4 [+4] Payload payload
-```
-
-This can be useful as a way to group related fields together.
-
-
### `external`
An `external` type is used when a type cannot be defined in Emboss itself;
