Make docs more cohesive with Timer constructors removal

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

docs/user-guide/utilities/timers.md

@@ -44,7 +44,7 @@
         show_root_toc_entry: false
         show_source: false
 
-## High-level Interface
+## Timer
 
 ::: frequenz.channels.timer.Timer
     options:
@@ -55,15 +55,7 @@
         show_root_toc_entry: false
         show_source: false
 
-
-## Low-level Interface
-
-A [`Timer`][frequenz.channels.timer.Timer] can be created using an arbitrary missed
-ticks policy by calling the [low-level
-constructor][frequenz.channels.timer.Timer.__init__] and passing the policy via the
-[`missed_tick_policy`][frequenz.channels.timer.Timer.missed_tick_policy] argument.
-
-### Custom Missed Tick Policies
+## Custom Missed Tick Policies
 
 ::: frequenz.channels.timer.MissedTickPolicy
     options:

src/frequenz/channels/timer.py

@@ -9,7 +9,7 @@
 [drifts](#missed-ticks-and-drifting)), you can use
 a [`Timer`][frequenz.channels.timer.Timer] like this:
 
-Example: Periodic Timer
+Example: Periodic Timer Example
     ```python
     import asyncio
     from datetime import datetime, timedelta
@@ -25,11 +25,16 @@ async def main() -> None:
     asyncio.run(main())
     ```
 
+    This timer will tick as close as every second as possible, even if the loop is busy
+    doing something else for a good amount of time. In extreme cases, if the loop was
+    busy for a few seconds, the timer will trigger a few times in a row to catch up, one
+    for every missed tick.
+
 If, instead, you need a timeout, for example to abort waiting for other receivers after
 a certain amount of time, you can use a [`Timer`][frequenz.channels.timer.Timer] like
 this:
 
-Example: Timeout
+Example: Timeout Example
     ```python
     import asyncio
     from datetime import timedelta
@@ -57,8 +62,10 @@ async def main() -> None:
     asyncio.run(main())
     ```
 
-    This timer will *rearm* itself automatically after it was triggered, so it will trigger
-    again after the selected interval, no matter what the current drift was.
+    This timer will *rearm* itself automatically after it was triggered, so it will
+    trigger again after the selected interval, no matter what the current drift was. So
+    if the loop was busy for a few seconds, the timer will trigger immediately and then
+    wait for another second before triggering again. The missed ticks are skipped.
 
 Tip:
     It is extremely important to understand how timers behave when they are
@@ -486,7 +493,7 @@ def __init__(  # pylint: disable=too-many-arguments
     ) -> None:
         """Create an instance.
 
-        See the class documentation for details.
+        See the [class documentation][frequenz.channels.timer.Timer] for details.
 
         Args:
             interval: The time between timer ticks. Must be at least