From 13a63d548c98699b5faf1bd5c680594a58b12e85 Mon Sep 17 00:00:00 2001
From: Jef Roosens <roosensjef@gmail.com>
Date: Sun, 22 Jan 2023 12:32:47 +0100
Subject: [PATCH 1/2] docs: added docstrings to public headers

---
 include/vieter_cron.h | 24 ++++++++++++++++++++++--
 include/vieter_heap.h | 18 ++++++++++++++++++
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/include/vieter_cron.h b/include/vieter_cron.h
index 9088d4d..8c50fff 100644
--- a/include/vieter_cron.h
+++ b/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
diff --git a/include/vieter_heap.h b/include/vieter_heap.h
index c7a9706..4c8d1e5 100644
--- a/include/vieter_heap.h
+++ b/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

From d11d0749608136d3a9c4e64e3411487a161d28cb Mon Sep 17 00:00:00 2001
From: Jef Roosens <roosensjef@gmail.com>
Date: Sun, 22 Jan 2023 12:35:55 +0100
Subject: [PATCH 2/2] chore: some reorganising

---
 README.md                    | 3 +++
 include/vieter_cron.h        | 1 -
 include/vieter_heap.h        | 1 -
 src/cron/vieter_cron_parse.c | 4 ++++
 4 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 9381fb1..0c33ab0 100644
--- a/README.md
+++ b/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.
diff --git a/include/vieter_cron.h b/include/vieter_cron.h
index 8c50fff..81a2630 100644
--- a/include/vieter_cron.h
+++ b/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>
diff --git a/include/vieter_heap.h b/include/vieter_heap.h
index 4c8d1e5..5d08ebc 100644
--- a/include/vieter_heap.h
+++ b/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;
diff --git a/src/cron/vieter_cron_parse.c b/src/cron/vieter_cron_parse.c
index 5c8da06..a82d1c3 100644
--- a/src/cron/vieter_cron_parse.c
+++ b/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,