added docs

include/collections/array.h

@@ -3,10 +3,10 @@
 
 #include <stdlib.h>
 
-// QUIP: is array useless, or at least not useful enough to just its existence rn
-//       solution: implicit allocation, so that the array manages its own heap-allocated data
+/// Fixed-size, checked array; more or less a "checked pointer". `array_t` makes no assumptions about how memory
+/// is allocated, but does perform bounds checking to ensure that accesses are within the bounds of the array,
+/// and does provide a simple search mechanism.
 
-// Fixed-size, checked array
 typedef struct {
     void* data;
     size_t len;

include/collections/linkedlist.h

@@ -3,6 +3,9 @@
 
 #include <stdlib.h>
 
+/// Implements a simple, singly-linked list. Elements can be inspected & inserted
+/// from the front & back of the list. Simple search & removal is also provided.
+
 struct ll_node {
     struct ll_node* next;
     void* data;

include/collections/set.h

@@ -9,6 +9,10 @@
 #define MAX_LOAD_FACTOR 0.5
 #define DEFAULT_BUCKETS (size_t)20
 
+/// A hash-based set, implemented with separate chaining collision resolution.
+/// Hash and equality functions must be provided; elements are stored in linked list-based buckets,
+/// and can be added or removed. Rehashing occurs when load factor reaches the max load factor listed above.
+
 typedef struct {
     hash_fn_t hash_fn;
     int (*elem_eq)(void*, void*); // equality between two elements

include/utils/hash.h

@@ -3,11 +3,19 @@
 
 #include <stdlib.h>
 
+/// A hash "trait" & simple hash functions. By "trait" I just mean general interface
+/// for implementing hashing -- it just specifies the contract required for hashing to work.
+/// Two hash functions are provided: one for ints and one for strings. Both are very simple,
+/// and are more or less the bare minimum in terms of actual functionality.
+
 typedef size_t (*hash_fn_t)(void*);
 
-// Not literally only operating on ints -- these hashes operate on anything that fits into a `size_t`
+/// So simple, it just returns the value itself. Note that this operates on anything that will fit
+/// in a `size_t`, not specifically the `int` type.
 size_t int_simple_hash(void* x);
 
+/// Hashes the string by calculating a polynomial of based on its characters. If the pointer provided
+/// is null, the function panics.
 size_t str_simple_hash(void* val);
 
 // TODO: more & better hashes

include/utils/panic.h

@@ -4,6 +4,10 @@
 #include <stdio.h>
 #include <stdlib.h>
 
+/// A simple error-handling system. Although there is no stack-unwinding, this system is just a simple
+/// way to print an error message to the user before exiting. It prints a message to stderr, along with
+/// some basic debug data that specifies where the error occurred.
+
 #define panic(status, fmt_str, ...) fprintf(stderr, "[%s:%d @ %s] program panicked due to error:\n\t" fmt_str "\n", \
                                             __FILE__, __LINE__, __FUNCTION__, ##__VA_ARGS__); \
                                     exit(status);