include: update uv_timer doc comments

joyent · Aug 15, 2012 · 90a75b0 · shigeki · Aug 15, 2012 · bnoordhuis
1 parent 2c3e8b6
commit 90a75b0
Showing 1 changed file with 21 additions and 8 deletions.
diff --git a/include/uv.h b/include/uv.h
@@ -1093,8 +1093,7 @@ UV_EXTERN int uv_async_send(uv_async_t* async);
 /*
  * uv_timer_t is a subclass of uv_handle_t.
  *
- * Wraps libev's ev_timer watcher. Used to get woken up at a specified time
- * in the future.
+ * Used to get woken up at a specified time in the future.
  */
 struct uv_timer_s {
   UV_HANDLE_FIELDS
@@ -1103,8 +1102,22 @@ struct uv_timer_s {
 
 UV_EXTERN int uv_timer_init(uv_loop_t*, uv_timer_t* timer);
 
-UV_EXTERN int uv_timer_start(uv_timer_t* timer, uv_timer_cb cb,
-    int64_t timeout, int64_t repeat);
+/*
+ * Start the timer. `timeout` and `repeat` are in milliseconds.
+ *
+ * If timeout is zero, the callback fires on the next tick of the event loop.
+ *
+ * If repeat is non-zero, the callback fires first after timeout milliseconds
+ * and then repeatedly after repeat milliseconds.
+ *
+ * timeout and repeat are signed integers but that will change in a future
+ * version of libuv. Don't pass in negative values, you'll get a nasty surprise
+ * when that change becomes effective.
+ */
+UV_EXTERN int uv_timer_start(uv_timer_t* timer,
+                             uv_timer_cb cb,
+                             int64_t timeout,
+                             int64_t repeat);
 
 UV_EXTERN int uv_timer_stop(uv_timer_t* timer);
 
@@ -1116,10 +1129,10 @@ UV_EXTERN int uv_timer_stop(uv_timer_t* timer);
 UV_EXTERN int uv_timer_again(uv_timer_t* timer);
 
 /*
- * Set the repeat value. Note that if the repeat value is set from a timer
- * callback it does not immediately take effect. If the timer was non-repeating
- * before, it will have been stopped. If it was repeating, then the old repeat
- * value will have been used to schedule the next timeout.
+ * Set the repeat value in milliseconds. Note that if the repeat value is set
+ * from a timer callback it does not immediately take effect. If the timer was
+ * non-repeating before, it will have been stopped. If it was repeating, then
+ * the old repeat value will have been used to schedule the next timeout.
  */
 UV_EXTERN void uv_timer_set_repeat(uv_timer_t* timer, int64_t repeat);