From ff15c4e01df275065933df13616d406d8855d7d8 Mon Sep 17 00:00:00 2001
From: Orkuncakilkaya <orkuncakilkaya@gmail.com>
Date: Sat, 29 Aug 2026 18:50:15 +0300
Subject: [PATCH] docs(types): document the fixeds and ptrs typed buffers

The type table lists fixeds (buffer of fixed values) and ptrs (buffer of
pointers) alongside words, but they had no reference pages. Add both, with
compilable examples; coverage inventory updated (types: 10 -> 12).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/language/types/type-fixeds.md | 23 +++++++++++++++++++++++
 docs/language/types/type-ptrs.md   | 25 +++++++++++++++++++++++++
 tools/docgen/inventory.json        | 16 +++++++++-------
 3 files changed, 57 insertions(+), 7 deletions(-)
 create mode 100644 docs/language/types/type-fixeds.md
 create mode 100644 docs/language/types/type-ptrs.md

diff --git a/docs/language/types/type-fixeds.md b/docs/language/types/type-fixeds.md
new file mode 100644
index 00000000..40e4bbaf
--- /dev/null
+++ b/docs/language/types/type-fixeds.md
@@ -0,0 +1,23 @@
+---
+id: type-fixeds
+name: fixeds
+category: types
+kind: type
+tokens: fixeds
+sig: fixeds
+tip: A buffer of fixed-point values — f[i] reads and writes a fixed.
+order: 8
+---
+
+A <code>fixeds</code> is a raw buffer whose elements are <code>fixed</code> (Q16.16) values: index it with <code>buffer[i]</code> to read or write a <code>fixed</code> directly, with no bounds checking. You obtain one by allocating raw storage with <code>words(n)</code> — each slot is 32 bits — and typing the binding as <code>fixeds</code> so that indexing uses the fixed-point element size. Reach for it when you want a tight, fixed-size numeric array with deterministic math — a table of speeds, per-tile weights, a heightfield — and a growable <code>[]fixed</code> slice would be more than you need.
+
+```ludic
+program Heights {
+  handler Setup phase Start {
+    let heights: fixeds = words(4)
+    heights[0] = fx(2)
+    heights[1] = heights[0] + fx(1)
+    print(flr(heights[1]))
+  }
+}
+```
diff --git a/docs/language/types/type-ptrs.md b/docs/language/types/type-ptrs.md
new file mode 100644
index 00000000..106d6e42
--- /dev/null
+++ b/docs/language/types/type-ptrs.md
@@ -0,0 +1,25 @@
+---
+id: type-ptrs
+name: ptrs
+category: types
+kind: type
+tokens: ptrs
+sig: ptrs
+tip: A buffer of pointers — p[i] reads and writes a ptr.
+order: 9
+---
+
+A <code>ptrs</code> is a raw buffer whose elements are pointers: index it with <code>buffer[i]</code> to read or write a <code>ptr</code>, with no bounds checking. Allocate the storage with <code>words(n)</code> (a pointer fits in a slot) and type the binding as <code>ptrs</code> so indexing uses the pointer element size. It is the low-level building block for hand-rolled data structures — a table of records made with <code>new</code>, a free list, a bucket array — for when you want manual control instead of a growable <code>[]T</code> slice.
+
+```ludic
+program Records {
+  property Position { column: int = 0, row: int = 0 }
+
+  handler Setup phase Start {
+    let slots: ptrs = words(2)
+    slots[0] = new Position
+    slots[1] = new Position
+    print(2)
+  }
+}
+```
diff --git a/tools/docgen/inventory.json b/tools/docgen/inventory.json
index 500acd22..882280e4 100644
--- a/tools/docgen/inventory.json
+++ b/tools/docgen/inventory.json
@@ -173,15 +173,17 @@
     "kw-enum"
   ],
   "types": [
-    "type-int",
-    "type-fixed",
     "type-bool",
-    "type-str",
-    "type-entity",
-    "type-ptr",
-    "type-words",
     "type-byte",
+    "type-entity",
+    "type-fixed",
+    "type-fixeds",
+    "type-int",
+    "type-ptr",
+    "type-ptrs",
+    "type-slices",
+    "type-str",
     "type-void",
-    "type-slices"
+    "type-words"
   ]
 }