doc(timeutil): init docs for timeutil

2 files changed, 36 insertions, 5 deletions

diff --git a/TODO b/TODO
index 9c206f5..0a8686f 100644
--- a/TODO
+++ b/TODO
@@ -6,4 +6,4 @@ tests for xml.c | id:b9e91d022be6bdc70e7ab082743826370b713c72
 improve man3 situation | id:bf918930f6361c30f288c42894cbf9b0541c3340
 use errno instead of returning HTTP status codes in make_index | id:bfa35c48dcedbecd3a951eba243c4840178289ed
 sandboxing, at least chroot | id:f209aec893fe310c8276f64f6ff4a3208a2a4f28
-document timeutil and stringutil | id:fd05b97115848a8b22231a477b8252373bd87264
+document stringutil | id:fd05b97115848a8b22231a477b8252373bd87264
diff --git a/timeutil.h b/timeutil.h
index 8ee39cc..7d0270e 100644
--- a/timeutil.h
+++ b/timeutil.h
@@ -1,12 +1,43 @@
+/*!
+ * @file
+ * @brief Utilities for rendering timestamps as strings
+ */
 enum time_format {
-    RSS_TIME_FORMAT,
-    ATOM_TIME_FORMAT,
-    HTML_TIME_FORMAT_READABLE
+    RSS_TIME_FORMAT,          //!< RFC822 formatted time with 4 instead of 2 year digits
+    ATOM_TIME_FORMAT,         //!< RFC3339 formatted time
+    HTML_TIME_FORMAT_READABLE //!< like `ATOM_TIME_FORMAT`, but with space between date and time
 };
 
+/*!
+ * @brief Maximum size necessary to contain the output of flocaltime()
+ */
 #define MAX_TIMESTR_SIZE 32
 // max HTML/Atom: 24 + NUL byte
 // max RSS:       31 + NUL byte
 
+/*!
+ * @brief Format given timestamp as a string in the local timezone
+ *
+ * flocaltime() is a wrapper around `strftime()` which supports
+ * a specific set of output formats. In contrast to `strftime()`
+ * it can output correct RFC3339 time strings and does localtime
+ * resolution for you.
+ *
+ * Example usage to print a RFC3339 formatted timestamp:
+ *
+ * ```
+ * time_t some_time;
+ * char strtime[MAX_TIMESTR_SIZE];
+ *
+ * if(flocaltime(strtime, ATOM_TIME_FORMAT, MAX_TIMESTR_SIZE, &some_time) > 0) {
+ *   puts(strtime);
+ * }
+ * ```
+ *
+ * @param b output buffer
+ * @param type time format to use for output
+ * @param size number of `char`s the buffer can hold
+ * @param time pointer to timestamp
+ * @return `0` on error, otherwise length of the string placed in `b` excluding terminating `NUL` byte
+ */
 size_t flocaltime(char *b, enum time_format type, size_t size, const time_t *time);
-