Add documentation to data structure code.

include/ht.h

@@ -5,12 +5,27 @@
 
 #include "libds.h"
 
+/**
+ * A linked list node used for hash table buckets.
+ * Contains a copy of the key that was used to store the
+ * data as to avoid conflicting hash functions.
+ */
 struct ht_node_s {
   void* key;
   void* data;
   struct ht_node_s* next;
 };
 
+/**
+ * A hash table struct.
+ * The struct contains function pointers to all necessary
+ * internal functions so that it can be customized to work with
+ * any kind of data. By default, it works with strings.
+ *
+ * The copy function, which is intended to use malloc(), should return
+ * NULL if the allocation failed - otherwise, there is no way for the
+ * hash table to know something went wrong.
+ */
 struct ht_s {
   struct ht_node_s* data[LIBDS_HT_SIZE];
   unsigned int (*hash_func)(void*);
@@ -22,18 +37,80 @@ struct ht_s {
 typedef struct ht_node_s ht_node;
 typedef struct ht_s ht;
 
-unsigned int ht_default_hash_func(void*);
-int ht_default_cmp_func(void*, void*);
-void* ht_default_copy_func(void*);
-void ht_default_free_func(void*);
+/**
+ * The default hash function.
+ * Uses FNV-1 hash, and assumes data is a string.
+ * @param key the data to hash.
+ * @return the produced hashed integer.
+ */
+unsigned int ht_default_hash_func(void* key);
+/**
+ * The default key comparison function.
+ * Assumes both keys are strings and uses strcmp.
+ * @param a the key to compare
+ * @param b the key compared against
+ * @return true if the keys represent the same string.
+ */
+int ht_default_cmp_func(void* a, void* b);
+/**
+ * The default key copy function.
+ * @param key the key being copied
+ * @return a pointer to the copy of the key.
+ */
+void* ht_default_copy_func(void* key);
+/**
+ * The default key free function. Simply calls free()
+ * @param key the key to free.
+ */
+void ht_default_free_func(void* key);
 
-void ht_init(ht*);
-void ht_free(ht*);
+/**
+ * Initializes the hash table with default values.
+ * @param ht the hash table to initialize.
+ */
+void ht_init(ht* ht);
+/**
+ * Frees the hash table and its internally allocated nodes.
+ * The data itself is left intact - use ht_foreach to free it
+ * if it is no longer used.
+ * @param ht the hash table to free.
+ */
+void ht_free(ht* ht);
 
-libds_result ht_put(ht*, void*, void*);
-void* ht_get(ht*, void*);
-void ht_remove(ht*, void*);
+/**
+ * Stores data into the hash table. Uses malloc for node allocation.
+ * @param ht the hash table to store data into.
+ * @param key the key to use to store the data.
+ * @param value the value to store.
+ * @return LIBDS_SUCCESS if all goes well, LIBDS_MALLOC if an allocation fails.
+ */
+libds_result ht_put(ht* ht, void* key, void* value);
+/**
+ * Retrieves a value from the hash table.
+ * @param ht the hash table to retrieve a value from.
+ * @param key the key to use to find the data.
+ * @return the data, or NULL if it is not found.
+ */
+void* ht_get(ht* ht, void* key);
+/**
+ * Removes a value from the hash table.
+ * @param ht the hash table to remove a value from.
+ * @param key the key to use to find the data.
+ */
+void ht_remove(ht* ht, void* key);
 
-int ht_foreach(ht*, void*, compare_func, foreach_func, ...);
+/**
+ * Runs through every element in the hash table, and compares it against the
+ * given data using the given comparison function. If the comparison function returns
+ * true, calls the foreach function, passing it the element and the variable argument list.
+ * Stops if any foreach function returns a nonzero code.
+ * @param ht the hash table to perform the operation on.
+ * @param data the data passed to the comparison function.
+ * @param compare the comparison function operating on the data and each element in the list.
+ * @param foreach the foreach function called on every element that is matched by the comparison function.
+ * @param ... variable arguments to be passed to the foreach function.
+ * @return the code returned by the foreach functions.
+ */
+int ht_foreach(ht* ht, void* data, compare_func compare, foreach_func foreach, ...);
 
 #endif

include/libds.h

@@ -3,12 +3,32 @@
 
 #include <stdarg.h>
 
+/**
+ * Enum representing return codes from error-prone libds functions.
+ */
 enum libds_result_e { LIBDS_SUCCESS, LIBDS_MALLOC };
 
 typedef enum libds_result_e libds_result;
+/**
+ * Comparison function type.
+ * Comparison functions are used in searches etc.
+ * The function should take two elements, and, if they match, return 1. Otherwise, it should
+ * return 0.
+ */
 typedef int (*compare_func)(void*, void*);
+/**
+ * Foreach function type.
+ * Foreach functions are passed to _foreach calls.
+ * The function should return 0 if all goes well, or a nonzero error code if there is an issue.
+ */
 typedef int (*foreach_func)(void*, va_list);
 
+/**
+ * A compare_func implementation that always returns true.
+ * @param a The first piece of data being compared
+ * @param b The second piece of data being compared
+ * @return always true, i.e 1
+ */
 int compare_always(void* a, void* b);
 
 #endif

include/vec.h

@@ -5,6 +5,11 @@
 
 #include "libds.h"
 
+/**
+ * A vector struct.
+ * The vector uses a dynamic array to accommodate all the elements.
+ * Whenever the size limit is reached, the vector allocates a new array that is two times bigger.
+ */
 struct vec_s {
   void* data;
   int capacity;
@@ -13,15 +18,66 @@ struct vec_s {
 
 typedef struct vec_s vec;
 
-libds_result vec_init(vec*);
-void vec_free(vec*);
+/**
+ * Initializes the vector. This uses malloc to get new memory for the array,
+ * and therefore can fail.
+ * @param vec the vector to initialize
+ * @return LIBDS_SUCCESS if all goes well, LIBDS_MALLOC if an allocation fails.
+ */
+libds_result vec_init(vec* vec);
+/**
+ * Frees the vector, also freeing the dynamic array it uses for storage.
+ * This leaves the data intact. Use vec_foreach to free the data if
+ * it is no longer used.
+ * @param vec the vector to free
+ */
+void vec_free(vec* vec);
 
-libds_result vec_add(vec*, void*);
-void vec_remove(vec*, void*);
+/**
+ * Adds an element to the vector
+ * @param vec the vector to add the value to
+ * @param val the value to add to the vector.
+ * @return LIBDS_SUCCESS if all goes wellm LIBDS_MALLOC if an allocation fails.
+ */
+libds_result vec_add(vec* vec, void* val);
+/**
+ * Removes the given value from the vector
+ * @param vec the vector to remove the value from
+ * @param val the value to remove
+ */
+void vec_remove(vec* vec, void* val);
 
-void* vec_find(vec*, void*, compare_func);
-int vec_foreach(vec*, void*, compare_func, foreach_func, ...);
+/**
+ * Runs through every element in the vector, and compares it against the
+ * given data using the given comparison function. If the comparison function returns
+ * true, returns the element that was passed to it. If the comparison function returns
+ * true for no element, returns NULL.
+ * @param vec the vector to iterate through.
+ * @param data the data to compare elements against
+ * @param compare the comparison function
+ * @return the first element that is matched by the comparison function, or NULL if none are matched.
+ */
+void* vec_find(vec* vec, void* data, compare_func compare);
+/**
+ * Runs through every element in the vector, and compares it against the
+ * given data using the given comparison function. If the comparison function returns
+ * true, calls the foreach function, passing it the element and the variable argument list.
+ * Stops if any foreach function returns a nonzero code.
+ * @param vec the vector to perform the operation on
+ * @param data the data to pass the comparison function
+ * @param compare the comparison function operating on the data and each element in the list.
+ * @param foreach the function to be called on every element recognized by the comparison function
+ * @param ... variable arguments to be passed on to the foreach function
+ * @return 0 if all goes well, or the first nonzero code returned by foreach.
+ */
+int vec_foreach(vec* vec, void* data, compare_func compare, foreach_func foreach, ...);
 
-void* vec_index(vec*, int);
+/**
+ * Gets the value at the given index of the vector.
+ * @param vec the vector to get the value from
+ * @param index the index to retreive a value from
+ * @return pointer to the value, or, if the index is out of bounds (or there is nothing there) NULL.
+ */
+void* vec_index(vec* vec, int index);
 
 #endif