[Python] Update bitfield documentation with better wording and another example

1 files changed, 26 insertions, 1 deletions

diff --git a/docs/dev/annotation.md b/docs/dev/annotation.md
index a341b566..24ff6de0 100644
--- a/docs/dev/annotation.md
+++ b/docs/dev/annotation.md
@@ -252,10 +252,35 @@ To create a bitfield in a structure, you can use the `bit_position` and `bit_wid
 ```
 
 It is important to note the distinction between the `bit_position` and `offset` parameters. The `offset` is a byte offset
-from the start of the structure, and the `bit_position` is a bit offset from the start of byte offset. The reason member
+from the start of the structure, and the `bit_position` is the bit from the start of byte offset the member resides at, `bit_position` **cannot** be greater than `7`. The reason member
 offsets are byte offsets instead of bit offsets is historical, previous versions of Binary Ninja had no concept of bitwise
 structures.
 
+For example, if you have a structure with the following members:
+
+```c
+struct SmallFuncHeader __packed
+{
+    uint32_t offset : 25;
+    uint32_t paramCount : 7;
+    uint32_t bytecodeSizeInBytes : 15;
+    uint32_t functionName : 17;
+};
+```
+
+This can be constructed in Python like so:
+
+```pycon
+>>> t = TypeBuilder.structure(packed=True)
+... t.insert(0, Type.int(4, False), "offset", bit_position=0, bit_width=25)
+... t.insert(3, Type.int(4, False), "paramCount", bit_position=1, bit_width=7)
+... t.insert(4, Type.int(4, False), "bytecodeSizeInBytes", bit_position=0, bit_width=15)
+... t.insert(5, Type.int(4, False), "functionName", bit_position=7, bit_width=17)
+... t.members
+... 
+[<uint32_t offset, offset 0x0, bit 0:25>, <uint32_t paramCount, offset 0x3, bit 1:7>, <uint32_t bytecodeSizeInBytes, offset 0x4, bit 0:15>, <uint32_t functionName, offset 0x5, bit 7:17>]
+```
+
 #### Create Enumerations
 
 ```python