Update: Improved documentation in headers

include/igloo/cs.h

@@ -28,19 +28,44 @@ extern "C" {
 
 /* All igloo_cs_*() functions MAY depend locale settings */
 
+/* Replaces a string in a safe way.
+ *
+ * This function replaces the string *dst with src.
+ * It calls free(3) on *dst to free the string if it is non-NULL.
+ * To copy the string strdup(3) is used.
+ *
+ * If memory can not be allocated *dst is kept unchanged.
+ */
 igloo_error_t igloo_cs_replace(const char *src, char **dst) igloo_ATTR_F_WARN_UNUSED_RESULT;
+
+/* Skips spaces in *str. This uses the same definition as isspace(3). */
 igloo_error_t igloo_cs_skip_spaces(const char **str);
 
+/* Converts strings to bools, ints, or unsigned ints.
+ *
+ * Range checking is performed.
+ * Bools support at least the values "true", "false", "yes", "no", "on", "off", "1", and "0".
+ * Other values may be supported depending on the locale.
+ */
 igloo_error_t igloo_cs_to_bool(const char *str, bool *res) igloo_ATTR_F_WARN_UNUSED_RESULT;
 igloo_error_t igloo_cs_to_int(const char *str, int *res) igloo_ATTR_F_WARN_UNUSED_RESULT;
 igloo_error_t igloo_cs_to_uint(const char *str, unsigned int *res) igloo_ATTR_F_WARN_UNUSED_RESULT;
 
+/* Convert strings in place to upper or lower case.
+ *
+ * The *_first() versions convert only the first letter.
+ * The conversation may depend on the locale.
+ */
 igloo_error_t igloo_cs_to_lower(char *str);
 igloo_error_t igloo_cs_to_upper(char *str);
 igloo_error_t igloo_cs_to_lower_first(char *str);
 igloo_error_t igloo_cs_to_upper_first(char *str);
 
+/* Convert a byte string into a string of hexpairs.
+ * The result is \0-terminated.
+ */
 igloo_error_t igloo_cs_to_hex(const void *in, char **res, size_t len) igloo_ATTR_F_WARN_UNUSED_RESULT;
+
 #ifdef __cplusplus
 }
 #endif

include/igloo/tap.h

@@ -38,7 +38,11 @@ typedef struct {
 #define igloo_TAP_EXIT_ON_FIN       0x04U // exit on finish
 #define igloo_TAP_EXIT_AFTER_GROUP  0x80U // delay exit to end of group (or finish)
 
+/* initialize a TAP test session */
 igloo_error_t   igloo_tap_init(void);
+/* finishes a TAP test session.
+ * This might also exit the process if igloo_TAP_EXIT_ON_FIN is set
+ */
 igloo_error_t   igloo_tap_fin(void);
 
 /* configure automatic exit of process.
@@ -53,22 +57,137 @@ igloo_error_t   igloo_tap_fin(void);
  */
 igloo_error_t   igloo_tap_exit_on(unsigned int flags, void (*cleanup)(void));
 
+/* Perform a basic test
+ *
+ * Parameters:
+ *  desc
+ *      Description/name of the test.
+ *  res
+ *      Whether the test succeeded or not.
+ */
 igloo_error_t   igloo_tap_test(const char *desc, bool res);
+
+/* Test for a function to return success.
+ *
+ * Parameters:
+ *  desc
+ *      Description/name of the test.
+ *  got
+ *      The error code returned (one of igloo_ERROR_*).
+ */
 #define         igloo_tap_test_success(desc, got) igloo_tap_test_error((desc), igloo_ERROR_NONE, (got))
+
+/* Test for a specific error code.
+ *
+ * Parameters:
+ *  desc
+ *      Description/name of the test.
+ *  expected
+ *      The error code expected (one of igloo_ERROR_*).
+ *  got
+ *      The error code got (one of igloo_ERROR_*).
+ */
 igloo_error_t   igloo_tap_test_error(const char *desc, igloo_error_t expected, igloo_error_t got);
+
+/* Writes a comment into the TAP log.
+ * Such comments can be useful to provide more information about a specific test or group of tests.
+ *
+ * Parameters:
+ *  line
+ *      The message to write.
+ */
 igloo_error_t   igloo_tap_diagnostic(const char *line);
+
+/* Performs a bail out.
+ * After a bail out testing should not continue.
+ *
+ * Parameters:
+ *  reason
+ *      The reason why the bail out happened.
+ *
+ * See also:
+ *  * igloo_tap_can_continue(),
+ *  * igloo_TAP_EXIT_ON_BAIL_OUT.
+ */
 igloo_error_t   igloo_tap_bail_out(const char *reason);
+
+/* Checks whether testing can continue */
 bool            igloo_tap_can_continue(igloo_error_t *error);
+
+/* Marks the beginning of a group of tests.
+ *
+ * Using igloo_tap_group_run() is preferable.
+ *
+ * Parameters:
+ *  group
+ *      Name of the group.
+ *
+ * See also:
+ *  * igloo_tap_group_end()
+ *  * igloo_tap_group_run().
+ */
 igloo_error_t   igloo_tap_group_begin(const char *group);
+
+/* Marks the end of a group of tests. */
 igloo_error_t   igloo_tap_group_end(void);
+
+/* Runs a function as a seperate group of tests.
+ *
+ * The group is only tested if testing can continue.
+ *
+ * Parameters:
+ *  group
+ *      Name of the group.
+ *  func
+ *      The function to run.
+ *
+ * See also:
+ *  * igloo_tap_can_continue().
+ */
 igloo_error_t   igloo_tap_group_run(const char *group, void (*func)(void));
 
 // useful helpers:
+/* Dumps an ro object as diagnostic.
+ *
+ * This function dumps an ro object as a set of diagnostic lines.
+ *
+ * Using igloo_tap_dump_ro_variable() is preferable.
+ *
+ * Parameters:
+ *  object
+ *      The object to dump.
+ *  name
+ *      The name of the object.
+ *
+ * See also:
+ *  * igloo_tap_dump_ro_variable().
+ */
 igloo_error_t   igloo_tap_dump_ro(igloo_ro_t object, const char *name);
+
+/* Dumps an ro object variable as diagnostic.
+ *
+ * This is the same as igloo_tap_dump_ro() but uses the name of the given variable
+ * as name.
+ *
+ * Parameters:
+ *  object
+ *      The object to dump.
+ *
+ * See also:
+ *  * igloo_tap_dump_ro().
+ */
 #define         igloo_tap_dump_ro_variable(var) igloo_tap_dump_ro((var), # var);
 
 // statistics:
+/* Gets current statistic about the tests.
+ *
+ * Parameters:
+ *  stats
+ *      Pointer to an igloo_tap_stats_t object to write to.
+ */
 #define         igloo_tap_get_stats(stats) igloo_tap_get_stats_real((stats), sizeof(igloo_tap_stats_t))
+
+/* Internal function, DO NOT call directly. */
 igloo_error_t   igloo_tap_get_stats_real(igloo_tap_stats_t *stats, size_t len);
 
 #ifdef __cplusplus

include/igloo/time.h

@@ -28,6 +28,7 @@ extern "C" {
 #include <igloo/types.h>
 
 typedef struct {
+    /* internal details. do not access directly! */
     uint32_t flags;
     uint32_t ssec;
     uint64_t fsec;
@@ -35,8 +36,8 @@ typedef struct {
 
 typedef uint32_t igloo_clock_t;
 
-#define igloo_CLOCK_REALTIME        ((igloo_clock_t)1)
-#define igloo_CLOCK_MONOTONIC       ((igloo_clock_t)2)
+#define igloo_CLOCK_REALTIME        ((igloo_clock_t)1) /* wall clock. Might jump by any amount in any direction. */
+#define igloo_CLOCK_MONOTONIC       ((igloo_clock_t)2) /* monotonic clock. Might not jump backwards. */
 
 /* Constant for the most monotonic clock that is available.
  * This should be used when sleeping or calculating time differences.
@@ -47,16 +48,36 @@ typedef uint32_t igloo_clock_t;
 #define igloo_CLOCK_MOST_MONOTONIC  igloo_CLOCK_MONOTONIC
 #endif
 
+/* Create a igloo_ctime_t representing a NULL-value.
+ *
+ * To create a zero value use igloo_ctime_from_time_t() or igloo_ctime_from_interval() with a value of 0.
+ */
 igloo_error_t   igloo_ctime_from_null(igloo_ctime_t *dst);
+
+/* Create a absolute igloo_ctime_t from a time_t. */
 igloo_error_t   igloo_ctime_from_time_t(igloo_ctime_t *dst, time_t src, igloo_clock_t clock);
+/* Create a interval igloo_ctime_t from a number of seconds + nano seconds. */
 igloo_error_t   igloo_ctime_from_interval(igloo_ctime_t *dst, uint64_t sec, uint32_t nsec, igloo_clock_t clock);
+/* Create a absolute igloo_ctime_t from the current time. */
 igloo_error_t   igloo_ctime_from_now(igloo_ctime_t *dst, igloo_clock_t clock);
+/* Convert a igloo_ctime_t to a time_t. */
 igloo_error_t   igloo_ctime_to_time_t(time_t *dst, igloo_ctime_t src);
+/* Sleep for the duration of a interval igloo_ctime_t. */
 igloo_error_t   igloo_ctime_sleep(igloo_ctime_t t);
+
+/* Check if a igloo_ctime_t is a NULL-value. */
 bool            igloo_ctime_is_null(igloo_ctime_t t);
+/* Check if a igloo_ctime_t is valid. */
 bool            igloo_ctime_is_valid(igloo_ctime_t t);
+/* Check if a igloo_ctime_t represents an interval. */
 bool            igloo_ctime_is_interval(igloo_ctime_t t);
+/* Ćheck if a igloo_ctime_t represents an absolute time. */
 bool            igloo_ctime_is_absolute(igloo_ctime_t t);
+/* Check if a igloo_ctime_t is negative.
+ *
+ * This can only return true for intervals as absolute times
+ * are always considered positive.
+ */
 bool            igloo_ctime_is_negative(igloo_ctime_t t);
 
 #ifdef __cplusplus