Commit aaee3270 authored by Philipp Schafft's avatar Philipp Schafft 🦁
Browse files

Update: Improved documentation in headers

parent da1ede1b
Pipeline #2748 passed with stages
in 3 minutes and 45 seconds
......@@ -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
......
......@@ -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
......
......@@ -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
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment