docs: added docstrings to public headers

include/vieter_cron.h

@@ -35,18 +35,38 @@ typedef struct vieter_cron_simple_time {
   int minute;
 } vieter_cron_simple_time;
 
+/*
+ * Allocate and initialize a new empty cron expression.
+ */
 vieter_cron_expression *ce_init();
 
+/*
+ * Deallocate a cron expression.
+ */
 void vieter_cron_expr_free(vieter_cron_expression *ce);
 
+/*
+ * Given a cron expression and a reference time, calculate the next time after
+ * the reference time that this expression matches.
+ */
 void vieter_cron_expr_next(vieter_cron_simple_time *out,
                            vieter_cron_expression *ce,
                            vieter_cron_simple_time *ref);
 
+/*
+ * Convencience wrapper around vieter_cron_expr_next that uses the current time
+ * as the reference time.
+ */
 void vieter_cron_expr_next_from_now(vieter_cron_simple_time *out,
                                     vieter_cron_expression *ce);
 
-enum vieter_cron_parse_error vieter_cron_expr_parse(vieter_cron_expression *out,
+/*
-                                                    const char *expression);
+ * Try to parse a string into a cron expression. Note that the cron expression
+ * is updated in-place, meaning it can contain invalid information if the
+ * function returns an error. The cron expression should only be used if the
+ * function succeeded.
+ */
+vieter_cron_parse_error vieter_cron_expr_parse(vieter_cron_expression *out,
+                                               const char *expression);
 
 #endif

include/vieter_heap.h

@@ -11,17 +11,35 @@ typedef enum vieter_heap_error {
   vieter_heap_empty = 1
 } vieter_heap_error;
 
+/*
+ * Allocate and initalize an empty heap.
+ */
 vieter_heap *vieter_heap_init();
 
+/*
+ * Deallocate a heap.
+ */
 void vieter_heap_free(vieter_heap *heap);
 
+/*
+ * Return how many elements are currently in the heap.
+ */
 uint64_t vieter_heap_size(vieter_heap *heap);
 
+/*
+ * Insert a new value into the heap.
+ */
 vieter_heap_error vieter_heap_insert(vieter_heap *heap, uint64_t key,
                                      void *data);
 
+/*
+ * Remove the smallest element from the heap.
+ */
 vieter_heap_error vieter_heap_pop(void **out, vieter_heap *heap);
 
+/*
+ * Get the smallest element in the heap without removing it.
+ */
 vieter_heap_error vieter_heap_peek(void **out, vieter_heap *heap);
 
 #endif