Fix #10, Update timing API documentation

Replicated changes to old documents that were
done previously.  Document/comment change only.

src/os/inc/osapi-os-timer.h

@@ -200,17 +200,28 @@ int32 OS_TimeBaseGetFreeRun     (uint32 timebase_id, uint32 *freerun_val);
  * @note clock_accuracy comes from the underlying OS tick value.  The nearest integer
  *       microsecond value is returned, so may not be exact.
  *
+ * @warning Depending on the OS, the timer_callback function may be similar to an
+ *          interrupt service routine. System calls the cause the code to block are
+ *          generally not supported.
+ *
  * @param[out]  timer_id        The resource ID of the timer object
  * @param[in]   timer_name      Name of the timer object
  * @param[out]  clock_accuracy  Expected precision of the timer, in microseconds. This
  *                              is the underlying tick value rounded to the nearest
  *                              microsecond integer.
- * @param[in]   callback_ptr    Application-provided function to invoke
+ * @param[in]   callback_ptr    The function pointer of the timer callback or ISR that
+ *                              will be called by the timer. The user’s function is
+ *                              declared as follows: <tt> void timer_callback(uint32 timer_id) </tt>
+ *                              Where the timer_id is passed in to the function by the OSAL
  *
  * @return Execution status, see @ref OSReturnCodes
  * @retval #OS_SUCCESS @copybrief OS_SUCCESS
  * @retval #OS_INVALID_POINTER if any parameters are NULL
- * @retval #OS_TIMER_ERR_INVALID_ARGS if the callback function is not valid
+ * @retval #OS_ERR_NAME_TOO_LONG if the name parameter is too long.
+ * @retval #OS_ERR_NAME_TAKEN if the name is already in use by another timer.
+ * @retval #OS_ERR_NO_FREE_IDS if all of the timers are already allocated.
+ * @retval #OS_TIMER_ERR_INVALID_ARGS if the callback pointer is zero.
+ * @retval #OS_TIMER_ERR_UNAVAILABLE if the timer cannot be created.
  */
 int32 OS_TimerCreate            (uint32 *timer_id, const char *timer_name, uint32 *clock_accuracy, OS_TimerCallback_t callback_ptr);
 
@@ -242,28 +253,34 @@ int32 OS_TimerAdd               (uint32 *timer_id, const char *timer_name, uint3
 
 /*-------------------------------------------------------------------------------------*/
 /**
- * @brief Configures the expiration time of the timer object
+ * @brief Configures a periodic or one shot timer
  *
- * Sets a timer to expire at the given start_time and
- * interval_time.  Units are the same as the underlying
- * time base object.  This is generally microseconds for
- * RTOS-provided (simulated) time base objects, but may be
- * different for BSP-provided time base objects.
+ * This function programs the timer with a start time and an optional interval time.
+ * The start time is the time in microseconds when the user callback function will be
+ * called. If the interval time is non-zero, the timer will be reprogrammed with that
+ * interval in microseconds to call the user callback function periodically. If the start
+ * time and interval time are zero, the function will return an error.
  *
  * For a "one-shot" timer, the start_time configures the
  * expiration time, and the interval_time should be passed as
  * zero to indicate the timer is not to be automatically reset.
  *
- * For a periodic timer, the interval_time indicates the
- * desired period between callbacks.
- *
- * The start_time and interval_time should not both be zero.
+ * @note The resolution of the times specified is limited to the clock accuracy
+ *       returned in the OS_TimerCreate call. If the times specified in the start_msec
+ *       or interval_msec parameters are less than the accuracy, they will be rounded
+ *       up to the accuracy of the timer.
  *
  * @param[in] timer_id      The timer ID to operate on
- * @param[in] start_time    Time to the first expiration
- * @param[in] interval_time Time between subsequent intervals
+ * @param[in] start_time    Time in microseconds to the first expiration
+ * @param[in] interval_time Time in microseconds between subsequent intervals, value
+ *                          of zero will only call the user callback function once
+ *                          after the start_msec time.
  *
  * @return Execution status, see @ref OSReturnCodes
+ * @retval #OS_SUCCESS @copybrief OS_SUCCESS
+ * @retval #OS_ERR_INVALID_ID if the timer_id is not valid.
+ * @retval #OS_TIMER_ERR_INTERNAL if there was an error programming the OS timer.
+ * @retval #OS_ERROR if both start time and interval time are zero. 
  */
 int32 OS_TimerSet               (uint32 timer_id, uint32 start_time, uint32 interval_time);
 
@@ -277,6 +294,9 @@ int32 OS_TimerSet               (uint32 timer_id, uint32 start_time, uint32 inte
  * @param[in] timer_id      The timer ID to operate on
  *
  * @return Execution status, see @ref OSReturnCodes
+ * @retval #OS_SUCCESS @copybrief OS_SUCCESS
+ * @retval #OS_ERR_INVALID_ID if the timer_id is invalid.
+ * @retval #OS_TIMER_ERR_INTERNAL if there was a problem deleting the timer in the host OS.
  */
 int32 OS_TimerDelete            (uint32 timer_id);
 
@@ -302,11 +322,16 @@ int32 OS_TimerGetIdByName       (uint32 *timer_id, const char *timer_name);
 /**
  * @brief Gets information about an existing timer
  *
- * This function will populate structure with
- * the relevant info (name and creator) about the specified timer.
+ * This function takes timer_id, and looks it up in the OS table. It puts all of the
+ * information known about that timer into a structure pointer to by timer_prop.
  *
  * @param[in]  timer_id      The timer ID to operate on
  * @param[out] timer_prop    Buffer containing timer properties
+ *                           - creator: the OS task ID of the task that created this timer
+ *                           - name: the string name of the timer
+ *                           - start_time: the start time in microseconds, if any
+ *                           - interval_time: the interval time in microseconds, if any
+ *                           - accuracy: the accuracy of the timer in microseconds
  *
  * @return Execution status, see @ref OSReturnCodes
  * @retval #OS_SUCCESS @copybrief OS_SUCCESS