From 5fd29f724110307e0ae6292d6db3f83b8d4a6c36 Mon Sep 17 00:00:00 2001 From: Joachim Nilsson Date: Mon, 20 Apr 2020 15:27:12 +0200 Subject: [PATCH] Clarify documentation of uev_timer_start() Signed-off-by: Joachim Nilsson --- src/timer.c | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/src/timer.c b/src/timer.c index b5c6556..444590f 100644 --- a/src/timer.c +++ b/src/timer.c @@ -49,18 +49,24 @@ static void msec2tspec(int msec, struct timespec *ts) * @param timeout Timeout in milliseconds before @param cb is called * @param period For periodic timers this is the period time that @param timeout is reset to * - * For one-shot timers you set @param period to zero and only use @param - * timeout. For periodic timers you likely set @param timeout to either - * zero, to call it as soon as the event loop starts, or to the same - * value as @param period. When the timer expires, the @param cb - * is called, with the optional @param arg argument. A non-periodic - * timer ends its life there, while a periodic task's @param timeout is - * reset to the @param period and restarted. + * This function creates, and optionally starts, a timer watcher. There + * are two types of timers: one-shot and periodic. + * + * One-shot timers only use @param timeout, @param period is zero. + * + * Periodic timers can either start their life disabled, with @param + * timeout set to zero, or with the same value as @param period. + * + * When the timeout expires, for either of the two types, @param cb is + * called, with the optional @param arg argument. A one-shot timer ends + * its life there, while a periodic task's @param timeout is reset to + * the @param period and restarted. * * A timer is automatically started if the event loop is already * running, otherwise it is kept on hold until triggered by calling * uev_run(). * + * @see uev_timer_set * @return POSIX OK(0) or non-zero with @param errno set on error. */ int uev_timer_init(uev_ctx_t *ctx, uev_t *w, uev_cb_t *cb, void *arg, int timeout, int period)