chore: some reorganising

README.md

@@ -36,6 +36,9 @@ All file names, function names... (even internals) should follow snake case
 convention and have a prefix unique to that module, starting with `vieter_`.
 For example, the `cron` modules uses the `vieter_cron_` prefix for everything.
 
+Header files should only import what they explicitely need. If some function is
+only used in a .c file, the import should be placed in the .c file instead.
+
 ### Testing
 
 This library uses [Acutest](https://github.com/mity/acutest) for its tests.

include/vieter_cron.h

@@ -1,7 +1,6 @@
 #ifndef VIETER_CRON
 #define VIETER_CRON
 
-#include <stdbool.h>
 #include <stdint.h>
 #include <stdlib.h>
 #include <string.h>
@@ -35,18 +34,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

@@ -1,7 +1,6 @@
 #ifndef VIETER_HEAP
 #define VIETER_HEAP
 
-#include <stddef.h>
 #include <stdint.h>
 
 typedef struct vieter_heap vieter_heap;
@@ -11,17 +10,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

src/cron/vieter_cron_parse.c

@@ -1,4 +1,8 @@
 #include "vieter_cron.h"
+#include <stdbool.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
 
 // This prefix is needed to properly compile
 const uint8_t parse_month_days[] = {31, 28, 31, 30, 31, 30,