Add documentation to time.h

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 214 insertions, 0 deletions

diff --git a/libsimple/time.h b/libsimple/time.h
index 7304030..e0f7603 100644
--- a/libsimple/time.h
+++ b/libsimple/time.h
@@ -1,23 +1,70 @@
 /* See LICENSE file for copyright and license details. */
 
+
+/**
+ * Calculates the sum of two `struct timespec`s
+ * 
+ * @param   sum     Output parameter for the result
+ * @param   augend  One of the terms
+ * @param   addend  The other term
+ * @return          0 on success, -1 on failure
+ * @throws  ERANGE  The result is too large or too small to be store; the result
+ *                  will be `{.tv_sec = TIME_MAX, .tv_nsec = 999999999L}` if the
+ *                  result too large and `{.tv_sec = TIME_MIN, .tv_nsec = 0L}`
+ *                  if the result too small
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__)))
 int libsimple_sumtimespec(struct timespec *, const struct timespec *, const struct timespec *);
 #ifndef sumtimespec
 # define sumtimespec libsimple_sumtimespec
 #endif
 
+
+/**
+ * Calculates the difference of two `struct timespec`s
+ * 
+ * @param   diff        Output parameter for the result
+ * @param   minuend     The left-hand term
+ * @param   subtrahend  The right-hand term
+ * @return              0 on success, -1 on failure
+ * @throws  ERANGE      The result is too large or too small to be store; the result
+ *                      will be `{.tv_sec = TIME_MAX, .tv_nsec = 999999999L}` if the
+ *                      result too large and `{.tv_sec = TIME_MIN, .tv_nsec = 0L}`
+ *                      if the result too small
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__)))
 int libsimple_difftimespec(struct timespec *, const struct timespec *, const struct timespec *);
 #ifndef difftimespec
 # define difftimespec libsimple_difftimespec
 #endif
 
+
+/**
+ * Calculates the product of a `struct timespec` and an integer
+ * 
+ * @param   prod          Output parameter for the result
+ * @param   multiplicand  One of the factors
+ * @param   multiplier    The other factor
+ * @return                0 on success, -1 on failure
+ * @throws  ERANGE        The result is too large or too small to be store; the result
+ *                        will be `{.tv_sec = TIME_MAX, .tv_nsec = 999999999L}` if the
+ *                        result too large and `{.tv_sec = TIME_MIN, .tv_nsec = 0L}`
+ *                        if the result too small
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__)))
 int libsimple_multimespec(struct timespec *, const struct timespec *, int);
 #ifndef multimespec
 # define multimespec libsimple_multimespec
 #endif
 
+
+/**
+ * Compares two `struct timespec`s
+ * 
+ * @param   a  One of the `struct timespec`s
+ * @param   b  The other `struct timespec`
+ * @return     -1 if `a` < `b`, 0 if `a` = `b`, and +1 if `a` > `b`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__, __warn_unused_result__)))
 static inline int
 libsimple_cmptimespec(const struct timespec *__a, const struct timespec *__b)
@@ -31,24 +78,70 @@ libsimple_cmptimespec(const struct timespec *__a, const struct timespec *__b)
 #endif
 
 
+/**
+ * Calculates the sum of two `struct timeval`s
+ * 
+ * @param   sum     Output parameter for the result
+ * @param   augend  One of the terms
+ * @param   addend  The other term
+ * @return          0 on success, -1 on failure
+ * @throws  ERANGE  The result is too large or too small to be store; the result
+ *                  will be `{.tv_sec = TIME_MAX, .tv_usec = 999999L}` if the
+ *                  result too large and `{.tv_sec = TIME_MIN, .tv_usec = 0L}`
+ *                  if the result too small
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__)))
 int libsimple_sumtimeval(struct timeval *, const struct timeval *, const struct timeval *);
 #ifndef sumtimeval
 # define sumtimeval libsimple_sumtimeval
 #endif
 
+
+/**
+ * Calculates the difference of two `struct timeval`s
+ * 
+ * @param   diff        Output parameter for the result
+ * @param   minuend     The left-hand term
+ * @param   subtrahend  The right-hand term
+ * @return              0 on success, -1 on failure
+ * @throws  ERANGE      The result is too large or too small to be store; the result
+ *                      will be `{.tv_sec = TIME_MAX, .tv_usec = 999999L}` if the
+ *                      result too large and `{.tv_sec = TIME_MIN, .tv_usec = 0L}`
+ *                      if the result too small
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__)))
 int libsimple_difftimeval(struct timeval *, const struct timeval *, const struct timeval *);
 #ifndef difftimeval
 # define difftimeval libsimple_difftimeval
 #endif
 
+
+/**
+ * Calculates the product of a `struct timeval` and an integer
+ * 
+ * @param   prod          Output parameter for the result
+ * @param   multiplicand  One of the factors
+ * @param   multiplier    The other factor
+ * @return                0 on success, -1 on failure
+ * @throws  ERANGE        The result is too large or too small to be store; the result
+ *                        will be `{.tv_sec = TIME_MAX, .tv_usec = 999999L}` if the
+ *                        result too large and `{.tv_sec = TIME_MIN, .tv_usec = 0L}`
+ *                        if the result too small
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__)))
 int libsimple_multimeval(struct timeval *, const struct timeval *, int);
 #ifndef multimeval
 # define multimeval libsimple_multimeval
 #endif
 
+
+/**
+ * Compares two `struct timeval`s
+ * 
+ * @param   a  One of the `struct timeval`s
+ * @param   b  The other `struct timeval`
+ * @return     -1 if `a` < `b`, 0 if `a` = `b`, and +1 if `a` > `b`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__, __warn_unused_result__)))
 static inline int
 libsimple_cmptimeval(const struct timeval *__a, const struct timeval *__b)
@@ -62,6 +155,12 @@ libsimple_cmptimeval(const struct timeval *__a, const struct timeval *__b)
 #endif
 
 
+/**
+ * Converts a `struct timeval` to a `struct timespec`
+ * 
+ * @param  ts  Output parameter for the result
+ * @param  tv  The value to convert
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__)))
 static inline void
 libsimple_timeval2timespec(struct timespec *restrict __ts, const struct timeval *restrict __tv)
@@ -74,36 +173,117 @@ libsimple_timeval2timespec(struct timespec *restrict __ts, const struct timeval
 # define timeval2timespec libsimple_timeval2timespec
 #endif
 
+
+/**
+ * Converts a `struct timespec` to a `struct timeval`
+ * 
+ * @param   tv         The value to convert
+ * @param   ts         Output parameter for the result
+ * @return             0 on success, -1 on error
+ * @throws  EOVERFLOW  The value is too large to be convert, the value will be
+ *                     truncated to `{.tv_sec = TIME_MAX, .tv_usec = 999999L}`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__)))
 int libsimple_timespec2timeval(struct timeval *restrict, const struct timespec *restrict);
 #ifndef timespec2timeval
 # define timespec2timeval libsimple_timespec2timeval
 #endif
 
+
+/**
+ * Converts a string to `struct timespec`
+ * 
+ * Repeating decimal are supported ith the repetend inside
+ * round brackets or after an additional point, for example
+ * "0.1(6)" or "0.1.6" for one sixth
+ *
+ * @param   ts      Output parameter for the result
+ * @param   s       The string to parse
+ * @param   end     Output parameter for where the parsing stopped;
+ *                  will only be set on success or on ERANGE error
+ * @return          0 on success, -1 on error
+ * @throws  EINVAL  The input string is invalid (`*end` is not set)
+ * @throws  ERANGE  The result is too large or too small to be store; the result
+ *                  will be `{.tv_sec = TIME_MAX, .tv_nsec = 999999999L}` if the
+ *                  result too large and `{.tv_sec = TIME_MIN, .tv_nsec = 0L}`
+ *                  if the result too small (`*end` is set)
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__(1, 2))))
 int libsimple_strtotimespec(struct timespec *restrict, const char *restrict, char **restrict);
 #ifndef strtotimespec
 # define strtotimespec libsimple_strtotimespec
 #endif
 
+
+/**
+ * Converts a string to `struct timeval`
+ * 
+ * Repeating decimal are supported ith the repetend inside
+ * round brackets or after an additional point, for example
+ * "0.1(6)" or "0.1.6" for one sixth
+ *
+ * @param   tv      Output parameter for the result
+ * @param   s       The string to parse
+ * @param   end     Output parameter for where the parsing stopped;
+ *                  will only be set on success or on ERANGE error
+ * @return          0 on success, -1 on error
+ * @throws  EINVAL  The input string is invalid (`*end` is not set)
+ * @throws  ERANGE  The result is too large or too small to be store; the result
+ *                  will be `{.tv_sec = TIME_MAX, .tv_usec = 999999L}` if the
+ *                  result too large and `{.tv_sec = TIME_MIN, .tv_usec = 0L}`
+ *                  if the result too small (`*end` is set)
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__(1, 2))))
 int libsimple_strtotimeval(struct timeval *restrict, const char *restrict, char **restrict);
 #ifndef strtotimeval
 # define strtotimeval libsimple_strtotimeval
 #endif
 
+
+/**
+ * Converts a `struct timespec` to string
+ * 
+ * The output will always have a sign ("+" or "-") and 9 decimals.
+ * 
+ * @param   buf     Output buffer to use, if `NULL` a new buffer will be allocated
+ * @param   ts      The value to convert
+ * @return          The result (same pointer as `buf` unless `buf == NULL`),
+ *                  `NULL` on failure
+ * @throws  ENOMEM  Output buffer could not be allocated (only if `buf == NULL`)
+ * @throws  EINVAL  `ts->tv_nsec` is negative or greater than 999999999
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__(2))))
 char *libsimple_timespectostr(char *restrict, const struct timespec *restrict);
 #ifndef timespectostr
 # define timespectostr libsimple_timespectostr
 #endif
 
+
+/**
+ * Converts a `struct timeval` to string
+ * 
+ * The output will always have a sign ("+" or "-") and 6 decimals.
+ * 
+ * @param   buf     Output buffer to use, if `NULL` a new buffer will be allocated
+ * @param   tv      The value to convert
+ * @return          The result (same pointer as `buf` unless `buf == NULL`),
+ *                  `NULL` on failure
+ * @throws  ENOMEM  Output buffer could not be allocated (only if `buf == NULL`)
+ * @throws  EINVAL  `ts->tv_usec` is negative or greater than 999999
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__(2))))
 char *libsimple_timevaltostr(char *restrict, const struct timeval *restrict);
 #ifndef timevaltostr
 # define timevaltostr libsimple_timevaltostr
 #endif
 
+
+/**
+ * Converts a `struct timespec` to `double`
+ * 
+ * @param   ts  The value to convert
+ * @return      The result
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__)))
 static inline double
 libsimple_timespectodouble(const struct timespec *__ts)
@@ -117,6 +297,13 @@ libsimple_timespectodouble(const struct timespec *__ts)
 # define timespectodouble libsimple_timespectodouble
 #endif
 
+
+/**
+ * Converts a `struct timeval` to `double`
+ * 
+ * @param   tv  The value to convert
+ * @return      The result
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__)))
 static inline double
 libsimple_timevaltodouble(const struct timeval *__tv)
@@ -130,18 +317,45 @@ libsimple_timevaltodouble(const struct timeval *__tv)
 # define timevaltodouble libsimple_timevaltodouble
 #endif
 
+
+/**
+ * Converts a double to `struct timespec`
+ * 
+ * No overflow check is made
+ * 
+ * @param  ts  Output parameter for the result
+ * @param  d   The value to convert
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__)))
 void libsimple_doubletotimespec(struct timespec *, double);
 #ifndef doubletotimespec
 # define doubletotimespec libsimple_doubletotimespec
 #endif
 
+
+/**
+ * Converts a double to `struct timeval`
+ * 
+ * No overflow check is made
+ * 
+ * @param  tv  Output parameter for the result
+ * @param  d   The value to convert
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__)))
 void libsimple_doubletotimeval(struct timeval *, double);
 #ifndef doubletotimeval
 # define doubletotimeval libsimple_doubletotimeval
 #endif
 
+
+/**
+ * Minimises a numerical string
+ * 
+ * This function does not support repeating decimals
+ * 
+ * @param   s  The string to minimise
+ * @return     `s`
+ */
 _LIBSIMPLE_GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__)))
 char *libsimple_minimise_number_string(char *);
 #ifndef minimise_number_string