Added documentation for the stm32_time module.

utils/include/stm32_time.h

+/** @file */
+
 #ifndef _STM32_TIME_H
 #define _STM32_TIME_H
 
+/**
+ * \brief Structure to handle blocking time delays and timeouts using a timer
+ *
+ * This structure is a wrapper around any timer in order to handle time delays
+ * and timeouts in a unified way. This structure requires a function to get the 
+ * accumulated number of counts of a timer and the number of timer counts per 
+ * micro-second of the timer.
+ *
+ * A single structure can only be used to handle a single timeout or delay, 
+ * but several structures can share a single timer without any performance 
+ * decrease.
+ *
+ * A time structure is first initialized by calling the time_init() function.
+ * Using this structure, it is possible to implement delays in
+ * seconds (time_delay_s()), milli-seconds (time_delay_ms()) and micro-seconds 
+ * (time_delay_us()), and also start (time_set_timeout()) and cancel 
+ * (time_cancel_timeout()) timeout, as well as checks its status (time_is_timeout()).
+ * 
+ */
 typedef struct
 {
+  /**
+   * \brief Target number of timer counts for the delay or timeout
+   *
+   * Absolute number of timer counts that must be reached to unblock any of the
+   * delay functions or activate the timeout feature. This value is internally
+   * computed taking into account the current number of counts and the desired
+   * time when any of the following functions are called:   
+   *   * time_set_timeout()
+   *   * time_delay_s()
+   *   * time_delay_ms()
+   *   * time_delay_us()
+   *
+   */
   unsigned long long int target_time;
+  /**
+   * \brief Number of timer counts per each micro-second
+   *
+   * This parameter holds the number of timer counts per each micro-second. This 
+   * parameter depends on the configuration of the associated timer and its value 
+   * must be provided when calling the time_init() function. This value should not 
+   * be modified afterwards. 
+   *
+   */
   int counts_per_us;
+  /**
+   * \brief Function pointer to get the accumulated number of counts of the timer
+   *
+   * The associated timer must provide a function which does not accept any parameters
+   * and returns the accumulated number of timer counts since the last reset as an
+   * unsigned long long variable (8 bytes in most architectures).
+   *
+   * This pointer must be provided at initilaization time when the time_init() function
+   * is called, and should not be modified afterwards.
+   *
+   */
   unsigned long long int (*get_time)(void);
 }TTime;
 
 /* public functions */
+/**
+ * \brief Function to initialize a time structure 
+ *
+ * This function initializes a time structure. This function must be called before
+ * calling any other function.
+ *
+ * \param time pointer to a valid TTime structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable.
+ * \param counts_per_us number of timer counts per micro-second. This value
+ *        must coincide with the actual value of the associated timer.
+ * \param get_time pointer to a function to get the accumulated number of
+ *        timer counts since the last reset. This function must be implemented 
+ *        by the associated timer module.
+ */
 void time_init(TTime *time,int counts_per_us,unsigned long long int(*get_time)(void));
+/**
+ * \brief Function to set the desired timeout in micro-seconds
+ *
+ * This functions sets the desired time to generate a timeout event if it is not
+ * canceller by the time_cancel_timeout() function. After calling this function,
+ * the time_is_timeout() function will return true if the current time is past
+ * the time when this function was called plus the desired timeout value.
+ * 
+ * If this function is called when there is an active timeout, the timeout
+ * condition is updated by the provided timeout value. This function activates
+ * the timeout, but it does not block. The time_is_timeout() function should be
+ * be used to check the state of the timeout, and the time_cancel_timeout()
+ * function to cancel it.
+ * 
+ * \param time pointer to a valid TTime structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable.
+ * \param timeout_us value of the desired timeout in micro-seconds. 
+ */
 void time_set_timeout(TTime *time,long int timeout_us);
+/**
+ * \brief Function to check if the desired time has elapsed
+ *
+ * This function checks whether the current time is past the time when the
+ * time_set_timeout() function was called plus the desired timeout or not.
+ * If this function will always return false if it is called when no timeout 
+ * has been activated by calling the time_set_timeout()
+ *
+ * \param time pointer to a valid TTime structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable.
+ *
+ * \return true if the timeout condition is active of false if the timeout
+ *         is not yet active or there is no timeout active.
+ */
 unsigned char time_is_timeout(TTime *time);
+/**
+ * \brief Function to cancel the current timeout
+ *
+ * This function cancels any timeout condition currently active. If no timeout
+ * is active when this function is called, nothing happens.
+ *
+ * \param time pointer to a valid TTime structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable.
+ */
 void time_cancel_timeout(TTime *time);
+/**
+ * \brief Function to wait a given time in micro-seconds
+ *
+ * This function blocks until the specifierd time in micro-seconds has elapsed.
+ * If this function is called when there is an active timeout, the timeout is 
+ * automatically cancelled.
+ * 
+ * \param time pointer to a valid TTime structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable.
+ * \param delay_us value of the desired delay in micro-seconds
+ */
 void time_delay_us(TTime *time,int delay_us);
+/**
+ * \brief Function to wait a given time in milli-seconds
+ *
+ * This function blocks until the specifierd time in milli-seconds has elapsed.
+ * If this function is called when there is an active timeout, the timeout is 
+ * automatically cancelled.
+ * 
+ * \param time pointer to a valid TTime structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable.
+ * \param delay_ms value of the desired delay in milli-seconds
+ */
 void time_delay_ms(TTime *time,int delay_ms);
+/**
+ * \brief Function to wait a given time in seconds
+ *
+ * This function blocks until the specifierd time in seconds has elapsed.
+ * If this function is called when there is an active timeout, the timeout is 
+ * automatically cancelled.
+ * 
+ * \param time pointer to a valid TTime structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable.
+ * \param delay_s value of the desired delay in seconds
+ */
 void time_delay_s(TTime *time,int delay_s);
 
 #endif