docs: Add some useful cross-references.

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

Author: llucax

src/frequenz/channels/anycast.py

@@ -19,9 +19,10 @@ class Anycast(Generic[T]):
     through a sender will be received by exactly one receiver.
 
     In cases where each message need to be received by every receiver, a
-    `Broadcast` channel may be used.
+    [Broadcast][frequenz.channels.Broadcast] channel may be used.
 
-    Uses an `deque` internally, so Anycast channels are not thread-safe.
+    Uses an [deque][collections.deque] internally, so Anycast channels are not
+    thread-safe.
 
     Example:
     ``` python
@@ -69,10 +70,13 @@ def __init__(self, maxsize: int = 10) -> None:
     async def close(self) -> None:
         """Close the channel.
 
-        Any further attempts to `send` data will return False.
+        Any further attempts to [send()][frequenz.channels.Sender.send] data
+        will return `False`.
 
         Receivers will still be able to drain the pending items on the channel,
-        but after that, subsequent `recv` calls will return None immediately.
+        but after that, subsequent
+        [receive()][frequenz.channels.Receiver.receive] calls will return `None`
+        immediately.
 
         """
         self.closed = True

src/frequenz/channels/base_classes.py

@@ -91,8 +91,9 @@ def into_peekable(self) -> "Peekable[T]":
 class Peekable(ABC, Generic[T]):
     """A base class for creating Peekables for peeking into channels.
 
-    A Peekable provides a `peek` method that allows the user to get a peek at
-    the latest value in the channel, without consuming anything.
+    A Peekable provides a [peek()][frequenz.channels.Peekable] method that
+    allows the user to get a peek at the latest value in the channel, without
+    consuming anything.
     """
 
     @abstractmethod

src/frequenz/channels/bidirectional.py

@@ -54,7 +54,7 @@ def service_handle(self) -> "BidirectionalHandle[U, T]":
 
 
 class BidirectionalHandle(Sender[T], Receiver[U]):
-    """A handle to a Bidirectional instance.
+    """A handle to a [Bidirectional][frequenz.channels.Bidirectional] instance.
 
     It can be used to send/receive values between the client and service.
     """

src/frequenz/channels/broadcast.py

@@ -25,8 +25,8 @@ class Broadcast(Generic[T]):
     receivers.
 
     Internally, a broadcast receiver's buffer is implemented with just
-    append/pop operations on either side of a `collections.deque`, which are
-    thread-safe.  Because of this, `Broadcast` channels are thread-safe.
+    append/pop operations on either side of a [deque][collections.deque], which
+    are thread-safe.  Because of this, `Broadcast` channels are thread-safe.
 
     Example:
     ``` python
@@ -83,10 +83,13 @@ def __init__(self, name: str, resend_latest: bool = False) -> None:
     async def close(self) -> None:
         """Close the Broadcast channel.
 
-        Any further attempts to `send` data will return False.
+        Any further attempts to [send()][frequenz.channels.Sender.send] data
+        will return `False`.
 
         Receivers will still be able to drain the pending items on their queues,
-        but after that, subsequent `recv` calls will return None immediately.
+        but after that, subsequent
+        [receive()][frequenz.channels.Receiver.receive] calls will return `None`
+        immediately.
         """
         self._latest = None
         self.closed = True
@@ -140,8 +143,9 @@ def get_receiver(
     def get_peekable(self) -> "Peekable[T]":
         """Create a new Peekable for the broadcast channel.
 
-        A Peekable provides a `peek` method that allows the user to get a peek
-        at the latest value in the channel, without consuming anything.
+        A Peekable provides a [peek()][frequenz.channels.Peekable.peek] method
+        that allows the user to get a peek at the latest value in the channel,
+        without consuming anything.
 
         Returns:
             A Peekable to peek into the broadcast channel with.
@@ -152,7 +156,8 @@ def get_peekable(self) -> "Peekable[T]":
 class Sender(BaseSender[T]):
     """A sender to send messages to the broadcast channel.
 
-    Should not be created directly, but through the `Channel.get_sender()`
+    Should not be created directly, but through the
+    [Broadcast.get_sender()][frequenz.channels.Broadcast.get_sender]
     method.
     """
 
@@ -188,7 +193,8 @@ async def send(self, msg: T) -> bool:
 class Receiver(BufferedReceiver[T]):
     """A receiver to receive messages from the broadcast channel.
 
-    Should not be created directly, but through the `Channel.get_receiver()`
+    Should not be created directly, but through the
+    [Broadcast.get_receiver()][frequenz.channels.Broadcast.get_receiver]
     method.
     """
 
@@ -253,8 +259,9 @@ async def receive(self) -> Optional[T]:
         them.  If there are no remaining messages in the buffer and the channel
         is closed, returns `None` immediately.
 
-        If `into_peekable` is called on a broadcast `Receiver`, further calls to
-        `receive`, will raise an `EOFError`.
+        If [into_peekable()][frequenz.channels.Receiver.into_peekable] is called
+        on a broadcast `Receiver`, further calls to `receive`, will raise an
+        `EOFError`.
 
         Raises:
             EOFError: when the receiver has been converted into a `Peekable`.
@@ -277,7 +284,8 @@ def into_peekable(self) -> "Peekable[T]":
         """Convert the `Receiver` implementation into a `Peekable`.
 
         Once this function has been called, the receiver will no longer be
-        usable, and calling `receive` on the receiver will raise an exception.
+        usable, and calling [receive()][frequenz.channels.Receiver.receive] on
+        the receiver will raise an exception.
 
         Returns:
             A `Peekable` instance.
@@ -290,8 +298,9 @@ def into_peekable(self) -> "Peekable[T]":
 class Peekable(BasePeekable[T]):
     """A Peekable to peek into broadcast channels.
 
-    A Peekable provides a `peek` method that allows the user to get a peek at
-    the latest value in the channel, without consuming anything.
+    A Peekable provides a [peek()][frequenz.channels.Peekable] method that
+    allows the user to get a peek at the latest value in the channel, without
+    consuming anything.
     """
 
     def __init__(self, chan: Broadcast[T]) -> None:

src/frequenz/channels/select.py

@@ -54,7 +54,7 @@ class Select:
     messages coming in the additional async iterators are dropped, and
     a warning message is logged.
 
-    `Receivers` also function as AsyncIterator.
+    [Receiver][frequenz.channels.Receiver]s also function as AsyncIterator.
     """
 
     def __init__(self, **kwargs: AsyncIterator[Any]) -> None:

src/frequenz/channels/utils/timer.py

@@ -65,16 +65,19 @@ def reset(self) -> None:
     def stop(self) -> None:
         """Stop the timer.
 
-        Once `stop` has been called, all subsequent calls to `receive` will
-        immediately return None.
+        Once `stop` has been called, all subsequent calls to
+        [receive()][frequenz.channels.Timer.receive] will immediately return
+        None.
         """
         self._stopped = True
 
     async def receive(self) -> Optional[datetime]:
         """Return the current time once the next tick is due.
 
         Returns:
-            The time of the next tick.
+            The time of the next tick or `None` if
+                [stop()][frequenz.channels.Timer.stop] has been called on the
+                timer.
         """
         if self._stopped:
             return None