more docs

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 {
     /**

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,