--- a/dowa/dowa.h	Mon Oct 06 10:13:41 2025 -0700
+++ b/dowa/dowa.h	Mon Oct 06 10:57:30 2025 -0700
@@ -4,8 +4,8 @@
 #include <stdio.h>
 #include <string.h> // stdup
 #include <stdlib.h> // only for malloc, free, stuff
-#include <assert.h>
-#include <dirent.h>
+#include <assert.h> // mostly for TODO
+#include <dirent.h> // some functions loop through files
 
 #include <sys/stat.h>
 #include <limits.h>
@@ -17,64 +17,82 @@
 #define TRUE  1
 #define FALSE 0
 
-typedef unsigned int uint32;
-typedef int int32;
-typedef unsigned short uint16;
-typedef short int16;
-typedef unsigned char uint8;
-typedef char int8;
-typedef char boolean;
+// Fixed-width integer types
+typedef unsigned int   uint32;   // 32-bit unsigned integer
+typedef int            int32;    // 32-bit signed integer
+typedef unsigned short uint16;   // 16-bit unsigned integer
+typedef short          int16;    // 16-bit signed integer
+typedef unsigned char  uint8;    // 8-bit unsigned integer
+typedef char           int8;     // 8-bit signed integer
+typedef char           boolean;  // Boolean type (0 = false, nonzero = true)
+
 
-// --- Misc --- //
-char *Dowa_Int32ToString(uint32 int32, char *buffer);
+// --- Miscellaneous --- //
+/* Just use atoid lmao*/
+char *Dowa_Int32ToString(uint32 value, char *buffer);
+
 
-// --- Arena --- //
+// --- Arena Allocator --- //
 typedef struct {
-  char   *buffer;
-  size_t offset;
-  size_t capacity;
+    char   *buffer;
+    size_t  offset;
+    size_t  capacity;
 } Dowa_Arena, *Dowa_PArena;
 
-extern Dowa_PArena  Dowa_Arena_Create(size_t capacity);
-extern void        *Dowa_Arena_Allocate(Dowa_PArena p_arena, size_t size);
-extern void         Dowa_Arena_Destory(Dowa_PArena p_arena);
+/* Creates a new arena with the specified capacity (in bytes). Returns a pointer to the arena, or NULL on failure. */
+extern       Dowa_PArena Dowa_Arena_Create(size_t capacity);
+/* Allocates a block of memory of the given size from the arena. Returns pointer to the allocated memory, or NULL if there is insufficient space. */
+extern void *Dowa_Arena_Allocate(Dowa_PArena arena, size_t size);
+/* Destroys the arena and frees its underlying memory block.*/
+extern void  Dowa_Arena_Destroy(Dowa_PArena arena);
+
 
 // --- HashMap --- //
 typedef enum {
-  DOWA_HASH_MAP_TYPE_BUFFER,
-  DOWA_HASH_MAP_TYPE_STRING,
-  DOWA_HASH_MAP_TYPE_HASHMAP,
-  DOWA_HASH_MAP_TYPE_INT,
+    DOWA_HASH_MAP_TYPE_BUFFER,   // Raw byte buffer
+    DOWA_HASH_MAP_TYPE_STRING,   // Null-terminated string
+    DOWA_HASH_MAP_TYPE_HASHMAP,  // Nested hashmap
+    DOWA_HASH_MAP_TYPE_INT       // Integer value
 } Dowa_HashMap_ValueType;
 
 typedef struct {
-  char           *key;
-  void           *buffer; 
-  size_t         capacity;
-  Dowa_HashMap_ValueType type;
+    char                  *key;
+    void                  *buffer;
+    size_t                 capacity;
+    Dowa_HashMap_ValueType type;
 } Dowa_HashEntry, *Dowa_PHashEntry;
 
 typedef struct {
-  Dowa_PHashEntry *entries;
-  size_t          capacity;
-  uint32          current_capacity;
-  Dowa_PArena     p_arena;
+    Dowa_PHashEntry *entries;
+    size_t           capacity;
+    uint32           current_capacity;
+    Dowa_PArena      p_arena;
 } Dowa_HashMap, *Dowa_PHashMap;
 
-extern Dowa_PHashMap   Dowa_HashMap_Create(size_t capacity);
-extern Dowa_PHashMap   Dowa_HashMap_Create(size_t capacity, Dowa_PArena p_arena);
-extern void            Dowa_HashMap_Destory(Dowa_PHashMap p_hash_map);
-extern int32           Dowa_HashMap_Get_Position(Dowa_PHashMap p_hash_map, char *key);
-extern void           *Dowa_HashMap_Get(Dowa_PHashMap p_hash_map, char *key);
-extern void            Dowa_HashMap_Push_Value(Dowa_PHashMap p_hash_map, char *key, void *value, size_t value_size);
-extern int32           Dowa_HashMap_Push_Value_With_Type_NoCopy(Dowa_PHashMap p_hash_map, char *key, void *value, size_t value_size, Dowa_HashMap_ValueType type);
-extern int32           Dowa_HashMap_Push_Value_With_Type(Dowa_PHashMap p_hash_map, char *key, void *value, size_t value_size, Dowa_HashMap_ValueType type);
-extern void            Dowa_HashMap_Pop_Key(Dowa_PHashMap p_hash_map, char *key);
+/* Creates a new hashmap with the given initial capacity. Returns pointer to the hashmap, or NULL on failure. */
+extern Dowa_PHashMap Dowa_HashMap_Create(size_t capacity);
+/* Creates a new hashmap with the given initial capacity, using the provided arena for all internal allocations. Returns pointer to the hashmap, or NULL on failure. */
+extern Dowa_PHashMap Dowa_HashMap_Create_With_Arena(size_t capacity, Dowa_PArena arena);
+/* Destroys the hashmap and frees all associated memory */
+extern void          Dowa_HashMap_Destroy(Dowa_PHashMap p_hash_map);
+/* Returns the index of the entry for the specified key, or -1 if the key is not found. */
+extern int32         Dowa_HashMap_Get_Position(Dowa_PHashMap p_hash_map, const char *key);
+/* Retrieves the value buffer for the specified key, or NULL if the key does not exist. */
+extern void         *Dowa_HashMap_Get(Dowa_PHashMap p_hash_map, const char *key);
+/* Inserts a copy of the given value into the hashmap under the specified key. Uses DOWA_HASH_MAP_TYPE_BUFFER as the entry type. */
+extern void          Dowa_HashMap_Push_Value(Dowa_PHashMap p_hash_map, const char *key, void *value, size_t value_size);
+/* Inserts a copy of the given value with the specified type into the hashmap under the key. Returns the index of the new entry, or -1 on failure. */
+extern int32         Dowa_HashMap_Push_Value_With_Type(Dowa_PHashMap p_hash_map, const char *key, void *value, size_t value_size, Dowa_HashMap_ValueType type);
+/* Inserts a value pointer into the hashmap under the specified key without copying data. The caller retains ownership of the pointer. Returns the entry index, or -1 on failure. */
+extern int32         Dowa_HashMap_Push_Value_With_Type_NoCopy(Dowa_PHashMap p_hash_map, const char *key, void *value, size_t value_size, Dowa_HashMap_ValueType type);
+/* Removes the entry with the specified key from the hashmap and frees its data if owned. */
+extern void          Dowa_HashMap_Pop_Key(Dowa_PHashMap p_hash_map, const char *key);
 
-// --- Maybe Useful --- //
-extern void Dowa_HashMap_Print(Dowa_PHashMap map);
-// 0 for success, -1 for failure. Get all files in the folder into key and vlaues.
-extern int  Dowa_HashMap_Cache_Folder(Dowa_PHashMap map, const char *folder_path);
+// --- Utility Functions --- //
+/* Prints all entries in the hashmap to stdout for debugging purposes. */
+extern void          Dowa_HashMap_Print(Dowa_PHashMap map);
+/* Loads all files from the specified folder into the hashmap. Uses file names as keys and file contents as values. Returns 0 on success, or -1 on failure. */
+extern int           Dowa_HashMap_Cache_Folder(Dowa_PHashMap map, const char *folder_path);
 
 
 #endif