Improve documentation (#136)

- Add missing enum members documentation
- Make cross-linking more consistent
- Improve Timer documentation

Author: llucax

src/frequenz/channels/util/_file_watcher.py

@@ -25,8 +25,13 @@ class EventType(Enum):
         """Available types of changes to watch for."""
 
         CREATE = Change.added
+        """A new file was created."""
+
         MODIFY = Change.modified
+        """An existing file was modified."""
+
         DELETE = Change.deleted
+        """An existing file was deleted."""
 
     @dataclass(frozen=True)
     class Event:

src/frequenz/channels/util/_select.py

@@ -18,7 +18,7 @@
 
 
 class Selected(Generic[_T]):
-    """A result of a [`select`][frequenz.channels.util.select] iteration.
+    """A result of a [`select()`][frequenz.channels.util.select] iteration.
 
     The selected receiver is consumed immediately and the received value is stored in
     the instance, unless there was an exception while receiving the value, in which case
@@ -28,7 +28,7 @@ class Selected(Generic[_T]):
     [`selected_from()`][frequenz.channels.util.selected_from] function to determine
     which receiver was selected.
 
-    Please see [`select`][frequenz.channels.util.select] for an example.
+    Please see [`select()`][frequenz.channels.util.select] for an example.
     """
 
     class _EmptyResult:
@@ -141,7 +141,7 @@ def __repr__(self) -> str:
 def selected_from(
     selected: Selected[Any], receiver: Receiver[_T]
 ) -> TypeGuard[Selected[_T]]:
-    """Check if the given receiver was selected by [`select`][frequenz.channels.util.select].
+    """Check if the given receiver was selected by [`select()`][frequenz.channels.util.select].
 
     This function is used in conjunction with the
     [`Selected`][frequenz.channels.util.Selected] class to determine which receiver was
@@ -150,7 +150,7 @@ def selected_from(
     It also works as a [type guard][typing.TypeGuard] to narrow the type of the
     `Selected` instance to the type of the receiver.
 
-    Please see [`select`][frequenz.channels.util.select] for an example.
+    Please see [`select()`][frequenz.channels.util.select] for an example.
 
     Args:
         selected: The result of a `select()` iteration.
@@ -165,7 +165,7 @@ def selected_from(
 
 
 class SelectError(BaseException):
-    """A base exception for [`select`][frequenz.channels.util.select].
+    """A base exception for [`select()`][frequenz.channels.util.select].
 
     This exception is raised when a `select()` iteration fails.  It is raised as
     a single exception when one receiver fails during normal operation (while calling
@@ -196,7 +196,7 @@ def __init__(self, selected: Selected[_T]) -> None:
 class SelectErrorGroup(BaseExceptionGroup[BaseException], SelectError):
     """An exception group for [`select()`][frequenz.channels.util.select] operation.
 
-    This exception group is raised when a [`select()`] loops fails while cleaning up
+    This exception group is raised when a `select()` loops fails while cleaning up
     runing tasts to check for ready receivers.
     """
 

src/frequenz/channels/util/_timer.py

@@ -270,36 +270,49 @@ def __repr__(self) -> str:
 class Timer(Receiver[timedelta]):
     """A timer receiver that triggers every `interval` time.
 
-    The timer as microseconds resolution, so the `interval` must be at least
+    The timer has microseconds resolution, so the
+    [`interval`][frequenz.channels.util.Timer.interval] must be at least
     1 microsecond.
 
-    The message it produces is a `timedelta` containing the drift of the timer,
-    i.e. the difference between when the timer should have triggered and the time
-    when it actually triggered.
+    The message it produces is a [`timedelta`][datetime.timedelta] containing the drift
+    of the timer, i.e. the difference between when the timer should have triggered and
+    the time when it actually triggered.
 
     This drift will likely never be `0`, because if there is a task that is
     running when it should trigger, the timer will be delayed. In this case the
     drift will be positive. A negative drift should be technically impossible,
-    as the timer uses `asyncio`s loop monotonic clock.
+    as the timer uses [`asyncio`][asyncio]s loop monotonic clock.
 
-    If the timer is delayed too much, then the timer will behave according to
-    the `missed_tick_policy`. Missing ticks might or might not trigger
-    a message and the drift could be accumulated or not depending on the
-    chosen policy.
+    If the timer is delayed too much, then it will behave according to the
+    [`missed_tick_policy`][frequenz.channels.util.Timer.missed_tick_policy]. Missing
+    ticks might or might not trigger a message and the drift could be accumulated or not
+    depending on the chosen policy.
 
-    The timer accepts an optional `loop`, which will be used to track the time.
-    If `loop` is `None`, then the running loop will be used (if there is no
-    running loop most calls will raise a `RuntimeError`).
+    These are the currently built-in available policies:
 
-    Starting the timer can be delayed if necessary by using `auto_start=False`
-    (for example until we have a running loop). A call to `reset()`, `ready()`,
-    `receive()` or the async iterator interface to await for a new message will
-    start the timer.
+    * [`SkipMissedAndDrift`][frequenz.channels.util.SkipMissedAndDrift]
+    * [`SkipMissedAndResync`][frequenz.channels.util.SkipMissedAndResync]
+    * [`TriggerAllMissed`][frequenz.channels.util.TriggerAllMissed]
 
     For the most common cases, a specialized constructor is provided:
 
-    * [`periodic()`][frequenz.channels.util.Timer.periodic]
-    * [`timeout()`][frequenz.channels.util.Timer.timeout]
+    * [`periodic()`][frequenz.channels.util.Timer.periodic] (uses the
+      [`TriggerAllMissed`][frequenz.channels.util.TriggerAllMissed] or
+      [`SkipMissedAndResync`][frequenz.channels.util.SkipMissedAndResync] policy)
+    * [`timeout()`][frequenz.channels.util.Timer.timeout] (uses the
+      [`SkipMissedAndDrift`][frequenz.channels.util.SkipMissedAndDrift] policy)
+
+    The timer accepts an optional [`loop`][frequenz.channels.util.Timer.loop], which
+    will be used to track the time. If `loop` is `None`, then the running loop will be
+    used (if there is no running loop most calls will raise
+    a [`RuntimeError`][RuntimeError]).
+
+    Starting the timer can be delayed if necessary by using `auto_start=False`
+    (for example until we have a running loop). A call to
+    [`reset()`][frequenz.channels.util.Timer.reset],
+    [`ready()`][frequenz.channels.util.Timer.ready],
+    [`receive()`][frequenz.channels.util.Timer.receive] or the async iterator interface
+    to await for a new message will start the timer.
 
     Example: Periodic timer example
         ```python