api: timer: improve documentation

Improved timer alloc and restart documentation. Functionality is
not changed.

Signed-off-by: Petri Savolainen <petri.savolainen@nokia.com>
Reviewed-by: Matias Elo <matias.elo@nokia.com>
Reviewed-by: Jerin Jacob <jerinj@marvell.com>

1 files changed, 18 insertions, 8 deletions

diff --git a/include/odp/api/spec/timer.h b/include/odp/api/spec/timer.h
index a50817c27..a6ad6f2b3 100644
--- a/include/odp/api/spec/timer.h
+++ b/include/odp/api/spec/timer.h
@@ -227,13 +227,20 @@ int odp_timer_pool_info(odp_timer_pool_t timer_pool,
 /**
  * Allocate a timer
  *
- * Create a timer (allocating all necessary resources e.g. timeout event) from
- * the timer pool. The user_ptr is copied to timeouts and can be retrieved
- * using the odp_timeout_user_ptr() call.
+ * Allocates a timer from the timer pool. Depending on timer type, the allocated timer is started
+ * with either odp_timer_start() or odp_timer_periodic_start() call. A timer may be reused multiple
+ * times before freeing it back into the timer pool.
+ *
+ * When timer expires, the timeout event defined in timer start parameters (see
+ * odp_timer_start_t::tmo_ev or odp_timer_periodic_start_t::tmo_ev) is sent into the provided
+ * destination queue.
+ *
+ * The provided user pointer value is copied into timeout events when the event type is
+ * ODP_EVENT_TIMEOUT. The value can be retrieved from an event with odp_timeout_user_ptr() call.
  *
  * @param timer_pool  Timer pool
- * @param queue       Destination queue for timeout notifications
- * @param user_ptr    User defined pointer or NULL to be copied to timeouts
+ * @param queue       Destination queue for timeout events
+ * @param user_ptr    User defined pointer value or NULL
  *
  * @return Timer handle on success
  * @retval ODP_TIMER_INVALID on failure
@@ -286,9 +293,12 @@ int odp_timer_start(odp_timer_t timer, const odp_timer_start_t *start_param);
  * Restart a timer
  *
  * A successful restart call updates the expiration time of an active timer. The timeout event
- * is not changed. The timer is not modified when a failure is returned. The call returns
- * ODP_TIMER_FAIL if the timer has expired already, or is so close to expire that it cannot be
- * restarted anymore.
+ * is not changed.
+ *
+ * The timer is not modified when a failure is returned. The call returns #ODP_TIMER_FAIL if
+ * the timer has expired already, or is so close to expire that it cannot be restarted anymore.
+ * A failure is returned also when the new expiration time is too near to the current time
+ * (#ODP_TIMER_TOO_NEAR) or too far from the current time (#ODP_TIMER_TOO_FAR).
  *
  * The new expiration time is passed the same way as with odp_timer_start() call.
  *