From 37372fa50bd5cd48125c9ed3abe378a8c3b15d1f Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <m@mitchellh.com>
Date: Wed, 24 Sep 2025 12:38:14 -0700
Subject: [PATCH] more docs

---
 include/ghostty/vt.h  | 19 ++++++++++++++++---
 src/lib/allocator.zig |  3 +++
 2 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/include/ghostty/vt.h b/include/ghostty/vt.h
index 90700e9c4..a1b1f221a 100644
--- a/include/ghostty/vt.h
+++ b/include/ghostty/vt.h
@@ -51,9 +51,22 @@ typedef enum {
  * This vtable defines the interface for a custom memory allocator. All
  * function pointers must be valid and non-NULL.
  *
- * NOTE(mitchellh): In the future, I think we can have default
- * implementations if resize/remap are null. alloc/free must always
- * be supplied.
+ * If you're not going to use a custom allocator, you can ignore all of
+ * this. All functions that take an allocator pointer allow NULL to use a
+ * default allocator.
+ *
+ * The interface is based on the Zig allocator interface. I'll say up front
+ * that it is easy to look at this interface and think "wow, this is really
+ * overcomplicated". The reason for this complexity is well thought out by
+ * the Zig folks, and it enables a diverse set of allocation strategies
+ * as shown by the Zig ecosystem. As a consolation, please note that many
+ * of the arguments are only needed for advanced use cases and can be
+ * safely ignored in simple implementations. For example, if you look at 
+ * the Zig implementation of the libc allocator in `lib/std/heap.zig`
+ * (search for CAllocator), you'll see it is very simple.
+ *
+ * NOTE(mitchellh): In the future, we can have default implementations of
+ * resize/remap and allow those to be null.
  */
 typedef struct {
     /**
diff --git a/src/lib/allocator.zig b/src/lib/allocator.zig
index 41e579f27..bcd7f9dcc 100644
--- a/src/lib/allocator.zig
+++ b/src/lib/allocator.zig
@@ -6,6 +6,7 @@ const testing = std.testing;
 pub const ZigVTable = std.mem.Allocator.VTable;
 
 /// The VTable required by the C interface.
+/// C: GhosttyAllocatorVtable
 pub const VTable = extern struct {
     alloc: *const fn (*anyopaque, len: usize, alignment: u8, ret_addr: usize) callconv(.c) ?[*]u8,
     resize: *const fn (*anyopaque, memory: [*]u8, memory_len: usize, alignment: u8, new_len: usize, ret_addr: usize) callconv(.c) bool,
@@ -37,6 +38,8 @@ pub fn default(c_alloc_: ?*const Allocator) std.mem.Allocator {
 /// the real world to be flexible and useful, and (2) it allows us to
 /// easily convert C allocators to Zig allocators and vice versa, since
 /// we're written in Zig.
+///
+/// C: GhosttyAllocator
 pub const Allocator = extern struct {
     ctx: *anyopaque,
     vtable: *const VTable,