doc: clarify repeating timer behavior more (#4640)

It was already documented but only in the uv_timer_set_repeat section.
Move it to the toplevel and flesh it out more.

Refs: https://github.com/libuv/libuv/issues/181
Refs: https://github.com/libuv/libuv/discussions/4639

1 files changed, 9 insertions, 5 deletions

diff --git a/docs/src/timer.rst b/docs/src/timer.rst
index 070fa79d..474c6b8c 100644
--- a/docs/src/timer.rst
+++ b/docs/src/timer.rst
@@ -6,6 +6,15 @@
 
 Timer handles are used to schedule callbacks to be called in the future.
 
+Timers are either single-shot or repeating. Repeating timers do not adjust
+for overhead but are rearmed relative to the event loop's idea of "now".
+
+Libuv updates its idea of "now" right before executing timer callbacks, and
+right after waking up from waiting for I/O. See also :c:func:`uv_update_time`.
+
+Example: a repeating timer with a 50 ms interval whose callback takes 17 ms
+to complete, runs again 33 ms later. If other tasks take longer than 33 ms,
+the timer callback runs as soon as possible.
 
 Data types
 ----------
@@ -64,11 +73,6 @@ API
     duration, and will follow normal timer semantics in the case of a
     time-slice overrun.
 
-    For example, if a 50ms repeating timer first runs for 17ms, it will be
-    scheduled to run again 33ms later. If other tasks consume more than the
-    33ms following the first timer callback, then the callback will run as soon
-    as possible.
-
     .. note::
         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,