From 59fa6ae852296fb598d43fc32b6ae24344d1759f Mon Sep 17 00:00:00 2001
From: Mason Reed <mason@vector35.com>
Date: Tue, 4 Nov 2025 13:29:08 -0500
Subject: [Python] Update bitfield documentation with better wording and
 another example

---
 docs/dev/annotation.md | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

(limited to 'docs/dev')

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
-- 
cgit v1.3.1