1 files changed, 115 insertions, 16 deletions

diff --git a/src/threadpool.h b/src/threadpool.h
index 7fda6f5..1d9a537 100644
--- a/src/threadpool.h
+++ b/src/threadpool.h
@@ -8,43 +8,142 @@ typedef struct task task;
 typedef struct taskqueue taskqueue;
 typedef struct ctqueue ctqueue;
 
-// Create a new task. Sets `errno` and returns `NULL` on error
+/**
+ * @brief Create a task
+ * 
+ * @param callback Callback function the given data should be ran with. Must be non-null
+ * @param freecb Callback function for freeing the given data. May be null
+ * @param data Data to be passed to the callback. May be null
+ * @return task* Returns a task object with set parameters. Returns `null` and sets errno on error
+ */
 task * task_init(gcallback callback, fcallback freecb, void *data);
-// Free a task. Passes the `.data` member to specified fcallback as a function parameter. Does not return a value or set `errno`
+
+/**
+ * @brief Free a task
+ * 
+ * @param tsk A task object to free. Frees data associated with task via `freecb` value specified in its creation. May be null
+ */
 void task_free(void *tsk);
-// Fire a task. Passes the `.data` member to specified gcallback as a function parameter. Returns value of gcallback, or sets `errno` and returns `-1` on error
+
+/**
+ * @brief Fire a task. Passes the `data` member to the specified `callback`
+ * 
+ * @param tsk A task to be fired. Must be non-null
+ * @return int Returns value of the fired callback. Returns -1 and sets errno on error
+ */
 int task_fire(task *tsk);
-// Fire and free a task simultaneously. Calls specified gcallback and fcallback on associated data. Returns value of gcallback, or sets `errno` and returns `-1` on error
+
+/**
+ * @brief Fire and destroy a task simultaneously. Calls specified callback and free-callback on associated data
+ * 
+ * @param tsk Task to be fired and destroyed. Must be non-null
+ * @return int Returns value of the callback. Returns -1 and sets errno on error
+ */
 int task_fired(task *tsk);                                              
 
 
 
-// Create a FIFO queue of task objects. Returns a new taskqueue on success, sets `errno` and returns `NULL` on error
+/**
+ * @brief Create a FIFO queue of tasks
+ * 
+ * @return taskqueue* Returns a new taskqueue object. Returns `null` and sets errno on error
+ */
 taskqueue * taskqueue_init(void);
-// Free a taskqueue. Does not return a value or set `errno`
+
+/**
+ * @brief Free a taskqueue
+ * 
+ * @param tq A taskqueue to be freed. May be null
+ */
 void taskqueue_free(void *tq);
-// Push a task onto the queue. Returns 0 on success, sets `errno` and returns `-1` on error
+
+/**
+ * @brief Push a task onto a taskqueue
+ * 
+ * @param tq The taskqueue to be modified. Must be non-null
+ * @param tsk The task to push. Must be non-null
+ * @return int Returns 0 on success, sets errno and returns -1 on error
+ */
 int taskqueue_push(taskqueue *tq, task *tsk);
-// Pop a task from the queue. Returns a task on success, sets `errno` and returns `NULL` on error
+
+/**
+ * @brief Pop a task from a taskqueue
+ * 
+ * @param tq A taskqueue to grab a task from. Must be non-null
+ * @return task* Returns a task on success, sets errno and returns `null` on error
+ */
 task * taskqueue_pop(taskqueue *tq);
-// Push a task to the front of the queue (append, task becomes first in line to be popped). Returns 0 on success, sets `errno` and returns `-1` on error
+
+/**
+ * @brief Append a task to the front of a taskqueue
+ * 
+ * @param tq The taskqueue to be modified. Must be non-null
+ * @param tsk The task to be appended. Must be non-null
+ * @return int Returns 0 on success, sets errno and returns `null` on error
+ */
 int taskqueue_pushfront(taskqueue *tq, task *tsk);
-// Pop a task from the back of the queue (pop the most recently (normally) pushed item). Returns a task on success, sets `errno` and returns `NULL` on error
+
+/**
+ * @brief Pop a task from the back (most recently pushed task) of a taskqueue
+ * 
+ * @param tq A taskqueue to pop from. Must be non-null
+ * @return task* Returns a task on success, sets errno and returns `null` on error
+ */
 task * taskqueue_popback(taskqueue *tq);
 
 
 
-// Create a concurrent taskqueue with `size` allocated threads
+/**
+ * @brief Create a concurrent taskqueue with `size` allocated threads
+ * 
+ * @param size Number of threads in the threadpool. Must be greater than zero
+ * @return ctqueue* Returns a new ctqueue, sets errno and returns `null` on error
+ */
 ctqueue * ctqueue_init(int size);
-// Cancel a currently running ctq
+
+/**
+ * @brief Cancel all tasks being processed in a currently running concurrent taskqueue
+ * 
+ * @param ctq The concurrent taskqueue to be canceled. Must be non-null
+ * @return int Returns 0 on success, sets errno and returns -1 on error
+ */
 int ctqueue_cancel(ctqueue *ctq);
-// Free a ctq (cancels any remaining operations)
+
+/**
+ * @brief Free a concurrent taskqueue
+ * @attention This cancels all currently running threads via `ctqueue_cancel`
+ *
+ * @param ctq The concurrent taskqueue to free. May be null
+ */
 void ctqueue_free(void *ctq);
-// Push a new task to the queue, waiting via mutex to do so
+
+/**
+ * @brief Push a task onto a concurrent taskqueue
+ * @attention May block for an indefinite amount of time to push the task
+ * 
+ * @param ctq The concurrent taskqueue to modify. Must be non-null
+ * @param tsk The task to push. Must be non-null
+ * @return Returns `thrd_success` on success, returns `thrd_error` or `thrd_nomem` on error
+ */
 int ctqueue_waitpush(ctqueue *ctq, task *tsk);
-// Pop a task from the queue, waiting via mutex to do so
+
+
+/**
+ * @brief Pop a task from the concurrent taskqueue
+ * @attention May block for an indefinite amount of time to pop the task
+ * 
+ * @param ctq The concurrent taskqueue to pop from. Must be non-null
+ * @return Returns a task on success, sets errno and returns `null` on error
+ */
 task * ctqueue_waitpop(ctqueue *ctq);
-// Spawn the allocated threads for a ctq
+
+/**
+ * @brief Start the threads allocated to a concurrent taskqueue
+ * @attention Threads will not consume pushed tasks until this function is ran 
+ *
+ * @param ctq A concurrent taskqueue to start. Must be non-null
+ * @return int Returns 0 on success, sets errno and returns -1 on error
+ */
 int ctqueue_start(ctqueue *ctq);
 
 #endif
\ No newline at end of file