doc: compliment and fix timex documentation

sys/include/timex.h

@@ -10,7 +10,11 @@
 
 /**
  * @defgroup    sys_timex Timex
+ * @brief       Timestamp representation, computation, and conversion
  * @ingroup     sys
+ *
+ * @{
+ * @file
  * @brief       Utility library for comparing and computing timestamps
  */
 
@@ -26,32 +30,73 @@
 #define PRIu32 "lu"
 #endif
 
+/**
+ * @brief The number of microseconds per second
+ */
 #define SEC_IN_USEC 1000000
 
+/**
+ * @brief The maximum length of the string representation of a timex timestamp
+ */
 #define TIMEX_MAX_STR_LEN   (18)
 
+/**
+ * @brief A timex timestamp
+ *
+ * @note  If a timestamp is not normalized, the number of microseconds might be
+ *        > 1000000
+ */
 typedef struct {
-    uint32_t seconds;
+    uint32_t seconds;       /**< number of seconds */
-    uint32_t microseconds;
+    uint32_t microseconds;  /**< number of microseconds */
 } timex_t;
 
-/* a+b */
+/**
+ * @brief Adds two timestamps
+ *
+ * @param[in] a     First summand
+ * @param[in] b     Second summand
+ *
+ * @return The sum of the two timestamps
+ */
 timex_t timex_add(const timex_t a, const timex_t b);
 
-/* a-b*/
+/**
+ * @brief Subtracts two timestamps
+ *
+ * @param[in] a     The minuend
+ * @param[in] b     The subtrahend
+ *
+ * @return The difference a - b
+ */
 timex_t timex_sub(const timex_t a, const timex_t b);
 
+/**
+ * @brief Initializes a timex timestamp
+ *
+ * @param[in] seconds       Number of seconds to set
+ * @param[in] microseconds  Number of microseconds to set
+ *
+ * @return The initialized timex timestamp
+ */
 timex_t timex_set(uint32_t seconds, uint32_t microseconds);
 
 /**
- * @brief Compares two timex values.
+ * @brief Compares two timex timestamps
  *
- * @return -1 when a is smaller, 0 if equal, 1 if a is bigger
+ * @param[in] a The first timestamp to compare to
+ * @param[in] b The second timestamp to compare with
+ *
+ * @return -1 when a is smaller
+ * @return 0 if equal
+ * @return 1 if a is bigger
  */
 int timex_cmp(const timex_t a, const timex_t b);
 
 /**
- * @brief Corrects timex_t structure so that microseconds < 1000000
+ * @brief Corrects timex structure so that microseconds < 1000000
+ *
+ * @param[in, out] time Pointer to the timestamp to normalize
  */
 static inline void timex_normalize(timex_t *time)
 {
@@ -60,9 +105,12 @@ static inline void timex_normalize(timex_t *time)
 }
 
 /**
- * @brief Tests a timex_t for normalization
+ * @brief Tests a timex timestamp for normalization
  *
- * @return true for a normalized timex_t, false otherwise
+ * @param[in] time  Pointer to the timestamp to check
+ *
+ * @return true for a normalized timex_t
+ * @return false otherwise
  */
 static inline int timex_isnormalized(timex_t *time)
 {
@@ -70,7 +118,9 @@ static inline int timex_isnormalized(timex_t *time)
 }
 
 /**
- * @brief Denormalizes a timex_t to a uint64_t
+ * @brief Converts a timex timestamp to a 64 bit value
+ *
+ * @param[in] a The timestamp to convert
  *
  * @return timex representation as uint64_t
  */
@@ -80,7 +130,9 @@ static inline uint64_t timex_uint64(const timex_t a)
 }
 
 /**
- * @brief Converts a uint64_t of microseconds to a timex_t
+ * @brief Converts a 64 bit value of microseconds to a timex timestamp
+ *
+ * @param[in] timestamp The timestamp to convert.
  *
  * @return a timex representation of an uint64 timestamp.
  */
@@ -90,7 +142,15 @@ static inline timex_t timex_from_uint64(const uint64_t timestamp)
 }
 
 /**
- * @brief Converts a timex_t to a struct
+ * @brief Converts a timex timestamp to a string
+ *
+ * @param[in]  t            The timestamp to convert
+ * @param[out] timestamp    The output char buffer for the converted timestamp
+ *
+ * @note The timestamp will be normalized
+ * @note The buffer must have a size of TIMEX_MAX_STR_LEN characters
+ *
+ * @return A pointer to the string representation of the timestamp
  */
 static inline const char *timex_to_str(timex_t t, char *timestamp)
 {
@@ -104,4 +164,5 @@ static inline const char *timex_to_str(timex_t t, char *timestamp)
     return timestamp;
 }
 
+/** @} */
 #endif /* __TIMEX_H */

sys/include/tm.h

@@ -9,6 +9,8 @@
 /**
  * @addtogroup  sys_timex
  * @{
+ *
+ * @file
  * @brief       Utility library for `struct tm`.
  */