docs: change docs to use the new declarative types and Annotated fields

Author: MrIndeciso

SKILL.md

@@ -25,6 +25,7 @@ Memory is accessed through an `inflater`, which wraps a `bytes` or `bytearray` b
 ### Imports
 
 ```python
+from typing import Annotated
 from libdestruct import (
     inflater,          # memory wrapper
     struct,            # struct base class
@@ -33,10 +34,10 @@ from libdestruct import (
     c_float, c_double, # IEEE 754 floats (32/64-bit)
     c_str,             # null-terminated C string
     ptr,               # 8-byte pointer
-    ptr_to,            # typed pointer field descriptor
-    ptr_to_self,       # self-referential pointer field descriptor
-    array_of,          # fixed-size array field descriptor
-    enum_of,           # enum field descriptor
+    ptr_to,            # typed pointer field descriptor (legacy)
+    ptr_to_self,       # self-referential pointer field descriptor (legacy)
+    array, array_of,   # array type + field descriptor
+    enum, enum_of,     # enum type + field descriptor
     bitfield_of,       # bitfield descriptor
     union,             # union annotation type
     union_of,          # plain union field descriptor
@@ -131,9 +132,21 @@ player = player_t.from_bytes(memory)
 ```python
 class node_t(struct):
     value: c_int
-    next: ptr = ptr_to_self()  # pointer to own type
+    next: ptr["node_t"]       # pointer to own type (forward ref)
 
 # Typed pointer to another type:
+class container_t(struct):
+    data: c_int
+    ref: ptr[c_long]          # subscript syntax (preferred)
+```
+
+Legacy syntax with `ptr_to()` and `ptr_to_self()` is still supported:
+
+```python
+class node_t(struct):
+    value: c_int
+    next: ptr = ptr_to_self()
+
 class container_t(struct):
     data: c_int
     ref: ptr = ptr_to(c_long)
@@ -176,7 +189,15 @@ class tree_t(struct):
 ```python
 class packet_t(struct):
     length: c_int
-    data: array_of(c_int, 8)  # fixed array of 8 c_int
+    data: array[c_int, 8]     # subscript syntax (preferred)
+```
+
+Legacy syntax with `array_of()` is still supported:
+
+```python
+class packet_t(struct):
+    length: c_int
+    data: array_of(c_int, 8)
 ```
 
 Access array elements:
@@ -199,6 +220,19 @@ class Color(IntEnum):
     GREEN = 1
     BLUE = 2
 
+class pixel_t(struct):
+    color: enum[Color]        # subscript syntax (preferred, defaults to c_int backing)
+    alpha: c_int
+
+# With a custom backing type:
+class pixel_t(struct):
+    color: enum[Color, c_short]  # 2-byte backing type
+    alpha: c_int
+```
+
+Legacy syntax with `enum_of()` is still supported:
+
+```python
 class pixel_t(struct):
     color: c_int = enum_of(Color)
     alpha: c_int
@@ -274,10 +308,29 @@ class wide_t(struct):
 
 ### Explicit Field Offsets
 
+```python
+from typing import Annotated
+
+class sparse_t(struct):
+    a: c_int
+    b: Annotated[c_int, offset(0x10)]  # Annotated syntax (preferred)
+```
+
+This works with any type, including subscript types:
+
+```python
+class example_t(struct):
+    a: c_int
+    data: Annotated[array[c_int, 4], offset(0x10)]
+    ref: Annotated[ptr[c_int], offset(0x20)]
+```
+
+Legacy syntax with default values is still supported:
+
 ```python
 class sparse_t(struct):
     a: c_int
-    b: c_int = offset(0x10)  # b starts at byte offset 0x10
+    b: c_int = offset(0x10)
 ```
 
 ### Nested Structs
@@ -374,7 +427,7 @@ class header_t(struct):
     magic: c_uint
     version: c_int
     num_entries: c_int
-    entries_ptr: ptr = ptr_to(entry_t)
+    entries_ptr: ptr[entry_t]
 
 with open("file.bin", "rb") as f:
     data = bytearray(f.read())

docs/advanced/c_parser.md

@@ -64,7 +64,7 @@ node_t = definition_to_type("""
 
 ## Arrays
 
-Fixed-size arrays are converted to `array_of()`:
+Fixed-size arrays are converted to `array[T, N]` types:
 
 ```python
 t = definition_to_type("""

docs/advanced/forward_refs.md

@@ -16,9 +16,9 @@ class Node(struct):
 
 At inflation time, the string `"Node"` is resolved to the actual `Node` class. This works because Python's `from __future__ import annotations` (used internally by libdestruct) defers annotation evaluation.
 
-## The `ptr_to_self` Shortcut
+## The Legacy `ptr_to_self` Shortcut
 
-For the common case of a pointer to the enclosing struct, use `ptr_to_self`:
+For the common case of a pointer to the enclosing struct, the legacy `ptr_to_self` syntax is also available:
 
 ```python
 from libdestruct import struct, c_int, ptr_to_self
@@ -28,7 +28,7 @@ class Node(struct):
     next: ptr_to_self
 ```
 
-This is equivalent to `ptr["Node"]` but doesn't require you to spell out the type name.
+This is equivalent to `ptr["Node"]` but doesn't require you to spell out the type name. The `ptr["TypeName"]` syntax is preferred as it is more explicit.
 
 ## Linked List Example
 

docs/advanced/offset.md

@@ -4,6 +4,35 @@ By default, struct fields are laid out sequentially — each field starts immedi
 
 ## Usage
 
+### Annotated syntax (preferred)
+
+Use `Annotated[T, offset(N)]` to place a field at a specific offset:
+
+```python
+from typing import Annotated
+from libdestruct import struct, c_int, offset
+
+class sparse_t(struct):
+    a: c_int
+    b: Annotated[c_int, offset(16)]
+    c: c_int
+```
+
+This works with any type, including subscript types:
+
+```python
+from libdestruct import struct, c_int, ptr, array, offset
+
+class example_t(struct):
+    a: c_int
+    data: Annotated[array[c_int, 4], offset(0x10)]
+    ref: Annotated[ptr[c_int], offset(0x20)]
+```
+
+### Legacy syntax
+
+The default-value syntax is also supported:
+
 ```python
 from libdestruct import struct, c_int, offset
 
@@ -49,8 +78,8 @@ C compilers often insert padding for alignment. Use `offset()` to match the actu
 
 class data_t(struct):
     flag: c_char
-    value: c_int = offset(4)
-    timestamp: c_long = offset(8)
+    value: Annotated[c_int, offset(4)]
+    timestamp: Annotated[c_long, offset(8)]
 ```
 
 ### Skipping Unknown Fields
@@ -59,13 +88,21 @@ When reverse engineering, you might know the offset of a field but not what come
 
 ```python
 class mystery_t(struct):
-    known_field: c_int = offset(0x40)
-    another_field: c_long = offset(0x100)
+    known_field: Annotated[c_int, offset(0x40)]
+    another_field: Annotated[c_long, offset(0x100)]
 ```
 
 ## Combining with Other Attributes
 
-`offset()` can be combined with `Field` attributes using a tuple:
+With the `Annotated` syntax, `offset()` can be combined with any type naturally:
+
+```python
+class example_t(struct):
+    data: Annotated[ptr[c_int], offset(8)]
+    items: Annotated[array[c_int, 4], offset(0x10)]
+```
+
+With the legacy syntax, `offset()` can be combined with `Field` attributes using a tuple:
 
 ```python
 from libdestruct.common.field import Field

docs/basics/arrays.md

@@ -1,13 +1,16 @@
 # Arrays
 
-Fixed-size arrays are created with `array_of()`.
+Fixed-size arrays can be defined using the `array[T, N]` subscript syntax or the `array_of()` factory function.
 
 ## Defining Arrays
 
 ```python
-from libdestruct import c_int, array_of, inflater
+from libdestruct import c_int, array, array_of, inflater
 
-# An array of 5 c_int values
+# Subscript syntax (preferred)
+int_array_t = array[c_int, 5]
+
+# Legacy factory function
 int_array_t = array_of(c_int, 5)
 ```
 
@@ -76,7 +79,16 @@ raw = bytes(arr)
 
 ## Arrays in Structs
 
-Use `array_of()` as a type annotation:
+Use `array[T, N]` as a type annotation:
+
+```python
+from libdestruct import struct, c_int, array
+
+class matrix_row_t(struct):
+    values: array[c_int, 4]
+```
+
+The legacy `array_of()` syntax is also supported:
 
 ```python
 from libdestruct import struct, c_int, array_of

docs/basics/enums.md

@@ -1,27 +1,45 @@
 # Enums
 
-libdestruct maps integer values in memory to Python `Enum` types using `enum_of()`.
+libdestruct maps integer values in memory to Python `Enum` types using the `enum[T]` subscript syntax or the `enum_of()` factory function.
 
 ## Defining Enums
 
 ```python
 from enum import IntEnum
-from libdestruct import struct, c_int, enum_of
+from libdestruct import struct, c_int, enum
 
 class Color(IntEnum):
     RED = 0
     GREEN = 1
     BLUE = 2
 
+# Subscript syntax (preferred)
+class pixel_t(struct):
+    color: enum[Color]        # defaults to c_int backing type
+    x: c_int
+    y: c_int
+
+# With a custom backing type:
+class pixel2_t(struct):
+    color: enum[Color, c_short]  # 2-byte backing type
+    x: c_int
+    y: c_int
+```
+
+The legacy `enum_of()` syntax is also supported:
+
+```python
+from libdestruct import struct, c_int, enum_of
+
 class pixel_t(struct):
     color: enum_of(Color, c_int)
     x: c_int
     y: c_int
 ```
 
-`enum_of(PythonEnum, backing_type)` creates a type that:
+The enum type:
 
-- Reads the raw integer from memory using the backing type (`c_int`)
+- Reads the raw integer from memory using the backing type (`c_int` by default)
 - Converts it to the corresponding `Enum` member (`Color.RED`, etc.)
 
 ## Reading Enum Values
@@ -51,19 +69,20 @@ print(pixel.color.value)  # 99 (raw integer, no error)
 
 ## Standalone Enums
 
-You can also use `enum` directly (without `enum_of`):
+You can also inflate enums directly outside of structs:
 
 ```python
 from libdestruct import enum, inflater
 
 memory = (2).to_bytes(4, "little")
 lib = inflater(memory)
 
-# The enum() constructor takes a resolver, a Python Enum, and a backing type
+e = lib.inflate(enum[Color], 0)
+print(e.value)  # Color.BLUE
 ```
 
 !!! tip
-    For struct fields, `enum_of()` is the recommended API. It automatically handles type registration and inflation.
+    For struct fields, the `enum[T]` subscript syntax is the recommended API. It automatically handles type registration and inflation.
 
 ## Serialization