More comments on the allocators.

lib/std/core/allocators/backed_arena_allocator.c3

@@ -1,12 +1,15 @@
 module std::core::mem::allocator;
 import std::io, std::math;
 
-struct AllocChunk @local
-{
-	usz size;
-	char[*] data;
-}
+<*
+ The backed arena allocator provides an allocator that will allocate from a pre-allocated chunk of memory
+ provided by it's backing allocator. The allocator supports mark / reset operations, so it can be used
+ as a stack (push-pop) allocator. If the initial memory is used up, it will fall back to regular allocations,
+ that will be safely freed on `reset`.
 
+ While this allocator is similar to the dynamic arena, it supports multiple "save points", which the dynamic arena
+ doesn't.
+*>
 struct BackedArenaAllocator (Allocator)
 {
 	Allocator backing_allocator;
@@ -16,6 +19,12 @@ struct BackedArenaAllocator (Allocator)
 	char[*] data;
 }
 
+struct AllocChunk @local
+{
+	usz size;
+	char[*] data;
+}
+
 const usz PAGE_IS_ALIGNED @local = (usz)isz.max + 1u;
 
 struct ExtraPage @local

lib/std/core/allocators/dynamic_arena.c3

@@ -4,6 +4,17 @@
 module std::core::mem::allocator;
 import std::math;
 
+<*
+ The dynamic arena allocator is an arena allocator that can grow by adding additional arena "pages".
+ It only supports reset, at which point all pages except the first one is released to the backing
+ allocator.
+
+ If you want multiple save points, use the BackedArenaAllocator instead.
+
+ The advantage over the BackedArenaAllocator, is that when allocating beyond the first "page", it will
+ retain the characteristics of an arena allocator (allocating a large piece of memory then handing off
+ memory from that memory), wheras the BackedArenaAllocator will have heap allocator characteristics.
+*>
 struct DynamicArenaAllocator (Allocator)
 {
 	Allocator backing_allocator;

lib/std/core/allocators/heap_allocator.c3

@@ -5,6 +5,13 @@
 module std::core::mem::allocator;
 import std::math;
 
+<*
+ The SimpleHeapAllocator implements a simple heap allocator on top of an allocator function.
+
+ It uses the given allocator function to allocate memory from some source, but never frees it.
+ This allocator is intended to be used in environments where there isn't any native libc malloc,
+ and it has to be emulated from a memory region, or wrapping linear memory as is the case for plain WASM.
+*>
 struct SimpleHeapAllocator (Allocator)
 {
 	MemoryAllocFn alloc_fn;

lib/std/core/allocators/libc_allocator.c3

@@ -1,13 +1,15 @@
-// Copyright (c) 2021-2024 Christoffer Lerno. All rights reserved.
+// Copyright (c) 2021-2025 Christoffer Lerno. All rights reserved.
 // Use of this source code is governed by the MIT license
 // a copy of which can be found in the LICENSE_STDLIB file.
-
 module std::core::mem::allocator @if(env::LIBC);
 import std::io;
 import libc;
 
-const LibcAllocator LIBC_ALLOCATOR = {};
+<*
+ The LibcAllocator is a wrapper around malloc to conform to the Allocator interface.
+*>
 typedef LibcAllocator (Allocator, Printable) = uptr;
+const LibcAllocator LIBC_ALLOCATOR = {};
 
 fn String LibcAllocator.to_string(&self, Allocator allocator) @dynamic => "Libc allocator".copy(allocator);
 fn usz? LibcAllocator.to_format(&self, Formatter *format) @dynamic => format.print("Libc allocator");

lib/std/core/allocators/on_stack_allocator.c3

@@ -1,5 +1,14 @@
 module std::core::mem::allocator;
 
+<*
+ The OnStackAllocator is similar to the ArenaAllocator: it allocates from a chunk of memory
+ given to it.
+
+ The difference is that when it runs out of memory it will go directly to its backing allocator
+ rather than failing.
+
+ It is utilized by the @stack_mem macro as an alternative to the temp allocator.
+*>
 struct OnStackAllocator (Allocator)
 {
 	Allocator backing_allocator;
@@ -8,7 +17,6 @@ struct OnStackAllocator (Allocator)
 	OnStackAllocatorExtraChunk* chunk;
 }
 
-
 struct OnStackAllocatorExtraChunk @local
 {
 	bool is_aligned;