Add documentation comments to thread pool

src/overture/thread_pool.h

@@ -2,10 +2,37 @@
 
 #include <stddef.h>
 
+/// @file
+///
+/// Simple thread pool based on POSIX threads.
+
 struct work_item;
 
+/// User function that processes a work item in the thread pool.
 typedef void (*work_fn_t)(struct work_item*, size_t);
 
+/// Work item that can be submitted to the thread pool. This is typically used as a member in a
+/// larger data structure which contains user data, such as the following example:
+///
+/// ```c
+/// struct my_work_item {
+///     struct work_item item;
+///     char* data;
+/// };
+/// void work_fn(struct work_item* item, size_t thread_id) {
+///     struct my_work_item* my_item = (struct my_work_item*)item;
+///     // do something with `my_item->data`
+/// }
+///
+/// // later in the program
+/// char* my_data = malloc(1000);
+/// struct my_work_item work = {
+///     .item.work_fn = work_fn,
+///     .data = my_data
+/// };
+/// thread_pool_submit(thread_pool, &my_work_item, &my_work_item);
+/// ```
+///
 struct work_item {
     work_fn_t work_fn;
     struct work_item* next;
@@ -24,6 +51,7 @@ size_t thread_pool_size(const struct thread_pool* thread_pool);
 /// Enqueues several work items in order on a thread pool, using locks to prevent data races.
 void thread_pool_submit(struct thread_pool* thread_pool, struct work_item* first, struct work_item* last);
 
-/// Waits for the given number of enqueued work items to terminate, or all of them if `count == 0`.
+/// Waits for enqueued work items to terminate.
+/// @param count Number of work items to wait for, or all of them if equal to 0.
 /// @return The executed work items for re-use.
 struct work_item* thread_pool_wait(struct thread_pool* thread_pool, size_t count);