From c3f01e77bc625347da569296adddf7dbb5d6eec9 Mon Sep 17 00:00:00 2001
From: Arthur Lafrance <lafrancearthur@gmail.com>
Date: Wed, 25 Aug 2021 13:15:19 -0700
Subject: [PATCH] added docs

---
 include/collections/array.h      |  6 +++---
 include/collections/linkedlist.h |  3 +++
 include/collections/set.h        |  4 ++++
 include/utils/error.h            |  0
 include/utils/hash.h             | 10 +++++++++-
 include/utils/panic.h            |  4 ++++
 6 files changed, 23 insertions(+), 4 deletions(-)
 delete mode 100644 include/utils/error.h

diff --git a/include/collections/array.h b/include/collections/array.h
index c627ea6..b9c71cc 100644
--- a/include/collections/array.h
+++ b/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;
diff --git a/include/collections/linkedlist.h b/include/collections/linkedlist.h
index fc36aa4..2f60df7 100644
--- a/include/collections/linkedlist.h
+++ b/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;
diff --git a/include/collections/set.h b/include/collections/set.h
index 47be0d5..98ed0a6 100644
--- a/include/collections/set.h
+++ b/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
diff --git a/include/utils/error.h b/include/utils/error.h
deleted file mode 100644
index e69de29..0000000
diff --git a/include/utils/hash.h b/include/utils/hash.h
index 30a0bf3..cc68575 100644
--- a/include/utils/hash.h
+++ b/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
diff --git a/include/utils/panic.h b/include/utils/panic.h
index d2afb46..cff8a5f 100644
--- a/include/utils/panic.h
+++ b/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);