1 files changed, 35 insertions, 4 deletions
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);
-