Improve documentation (#279)

This PR includes a lot of small documentation improvements and fixes,
trying to make the documentation more consistent and easier to read.

The commits are not particularly very well split, as many stuff was done
in parallel and the splitting was done afterwards. Cleaning it up is
very time demaning as it produces a lot of conflicts when rebasing.

Author: llucax

docs/user-guide/receiving/synchronization/index.md

@@ -5,7 +5,7 @@ could be difficult to, for example, receive the first message of each receiver
 as soon as it is available in one single task. A naive approach like this will
 not work:
 
-```python
+```python show_lines="4:"
 receiver1: Receiver[int] = channel1.new_receiver()
 receiver2: Receiver[int] = channel2.new_receiver()
 

mkdocs.yml

@@ -119,6 +119,7 @@ plugins:
             show_root_members_full_path: true
             show_signature_annotations: true
             show_source: true
+            show_symbol_type_toc: true
             signature_crossrefs: true
           import:
             # See https://mkdocstrings.github.io/python/usage/#import for details

src/frequenz/channels/__init__.py

@@ -6,6 +6,9 @@
 This package contains
 [channel](https://en.wikipedia.org/wiki/Channel_(programming)) implementations.
 
+<!-- For the full documentation and user guide please visit the [project's
+website](https://frequenz-floss.github.io/frequenz-channels-python/) -->
+
 Base classes:
 
 * [Receiver][frequenz.channels.Receiver]: An object that can wait for and

src/frequenz/channels/_anycast.py

@@ -197,7 +197,7 @@ async def main() -> None:
     """
 
     def __init__(self, *, name: str, limit: int = 10) -> None:
-        """Create an Anycast channel.
+        """Initialize this channel.
 
         Args:
             name: The name of the channel. This is for logging purposes, and it will be
@@ -275,7 +275,6 @@ async def close(self) -> None:
         but after that, subsequent
         [receive()][frequenz.channels.Receiver.receive] calls will return `None`
         immediately.
-
         """
         self._closed = True
         async with self._send_cv:
@@ -284,19 +283,11 @@ async def close(self) -> None:
             self._recv_cv.notify_all()
 
     def new_sender(self) -> Sender[_T]:
-        """Create a new sender.
-
-        Returns:
-            A Sender instance attached to the Anycast channel.
-        """
+        """Return a new sender attached to this channel."""
         return _Sender(self)
 
     def new_receiver(self) -> Receiver[_T]:
-        """Create a new receiver.
-
-        Returns:
-            A Receiver instance attached to the Anycast channel.
-        """
+        """Return a new receiver attached to this channel."""
         return _Receiver(self)
 
     def __str__(self) -> str:
@@ -319,7 +310,7 @@ class _Sender(Sender[_T]):
     """
 
     def __init__(self, chan: Anycast[_T]) -> None:
-        """Create a channel sender.
+        """Initialize this sender.
 
         Args:
             chan: A reference to the channel that this sender belongs to.
@@ -339,7 +330,7 @@ async def send(self, msg: _T) -> None:
             msg: The message to be sent.
 
         Raises:
-            SenderError: if the underlying channel was closed.
+            SenderError: If the underlying channel was closed.
                 A [ChannelClosedError][frequenz.channels.ChannelClosedError] is
                 set as the cause.
         """
@@ -387,7 +378,7 @@ class _Receiver(Receiver[_T]):
     """
 
     def __init__(self, chan: Anycast[_T]) -> None:
-        """Create a channel receiver.
+        """Initialize this receiver.
 
         Args:
             chan: A reference to the channel that this receiver belongs to.
@@ -431,8 +422,8 @@ def consume(self) -> _T:
             The next value that was received.
 
         Raises:
-            ReceiverStoppedError: if the receiver stopped producing messages.
-            ReceiverError: if there is some problem with the receiver.
+            ReceiverStoppedError: If the receiver stopped producing messages.
+            ReceiverError: If there is some problem with the receiver.
         """
         if (  # pylint: disable=protected-access
             self._next is _Empty and self._chan._closed

src/frequenz/channels/_broadcast.py

@@ -184,7 +184,7 @@ async def main() -> None:
     """
 
     def __init__(self, *, name: str, resend_latest: bool = False) -> None:
-        """Create a Broadcast channel.
+        """Initialize this channel.
 
         Args:
             name: The name of the channel. This is for logging purposes, and it will be
@@ -246,7 +246,7 @@ def is_closed(self) -> bool:
         return self._closed
 
     async def close(self) -> None:
-        """Close the Broadcast channel.
+        """Close this channel.
 
         Any further attempts to [send()][frequenz.channels.Sender.send] data
         will return `False`.
@@ -262,15 +262,11 @@ async def close(self) -> None:
             self._recv_cv.notify_all()
 
     def new_sender(self) -> Sender[_T]:
-        """Create a new broadcast sender.
-
-        Returns:
-            A Sender instance attached to the broadcast channel.
-        """
+        """Return a new sender attached to this channel."""
         return _Sender(self)
 
     def new_receiver(self, *, name: str | None = None, limit: int = 50) -> Receiver[_T]:
-        """Create a new broadcast receiver.
+        """Return a new receiver attached to this channel.
 
         Broadcast receivers have their own buffer, and when messages are not
         being consumed fast enough and the buffer fills up, old messages will
@@ -281,7 +277,7 @@ def new_receiver(self, *, name: str | None = None, limit: int = 50) -> Receiver[
             limit: Number of messages the receiver can hold in its buffer.
 
         Returns:
-            A Receiver instance attached to the broadcast channel.
+            A new receiver attached to this channel.
         """
         recv: _Receiver[_T] = _Receiver(name, limit, self)
         self._receivers[hash(recv)] = weakref.ref(recv)
@@ -290,7 +286,7 @@ def new_receiver(self, *, name: str | None = None, limit: int = 50) -> Receiver[
         return recv
 
     def __str__(self) -> str:
-        """Return a string representation of this receiver."""
+        """Return a string representation of this channel."""
         return f"{type(self).__name__}:{self._name}"
 
     def __repr__(self) -> str:
@@ -313,7 +309,7 @@ class _Sender(Sender[_T]):
     """
 
     def __init__(self, chan: Broadcast[_T]) -> None:
-        """Create a Broadcast sender.
+        """Initialize this sender.
 
         Args:
             chan: A reference to the broadcast channel this sender belongs to.
@@ -328,7 +324,7 @@ async def send(self, msg: _T) -> None:
             msg: The message to be broadcast.
 
         Raises:
-            SenderError: if the underlying channel was closed.
+            SenderError: If the underlying channel was closed.
                 A [ChannelClosedError][frequenz.channels.ChannelClosedError] is
                 set as the cause.
         """
@@ -369,7 +365,7 @@ class _Receiver(Receiver[_T]):
     """
 
     def __init__(self, name: str | None, limit: int, chan: Broadcast[_T]) -> None:
-        """Create a broadcast receiver.
+        """Initialize this receiver.
 
         Broadcast receivers have their own buffer, and when messages are not
         being consumed fast enough and the buffer fills up, old messages will
@@ -457,7 +453,7 @@ def consume(self) -> _T:
             The next value that was received.
 
         Raises:
-            ReceiverStoppedError: if there is some problem with the receiver.
+            ReceiverStoppedError: If there is some problem with the receiver.
         """
         if not self._q and self._chan._closed:  # pylint: disable=protected-access
             raise ReceiverStoppedError(self) from ChannelClosedError(self._chan)

src/frequenz/channels/_exceptions.py

@@ -70,45 +70,45 @@
 
 
 class Error(RuntimeError):
-    """Base error.
+    """An error that originated in this library.
 
-    All exceptions generated by this library inherit from this exception.
+    This is useful if you want to catch all exceptions generated by this library.
     """
 
     def __init__(self, message: str):
-        """Create a ChannelError instance.
+        """Initialize this error.
 
         Args:
-            message: An error message.
+            message: The error message.
         """
         super().__init__(message)
 
 
 class ChannelError(Error):
-    """An error produced in a channel.
+    """An error that originated in a channel.
 
     All exceptions generated by channels inherit from this exception.
     """
 
     def __init__(self, message: str, channel: Any):
-        """Create a ChannelError instance.
+        """Initialize this error.
 
         Args:
-            message: An error message.
-            channel: A reference to the channel that encountered the error.
+            message: The error message.
+            channel: The channel where the error happened.
         """
         super().__init__(message)
         self.channel: Any = channel
         """The channel where the error happened."""
 
 
 class ChannelClosedError(ChannelError):
-    """Error raised when trying to operate on a closed channel."""
+    """A closed channel was used."""
 
     def __init__(self, channel: Any):
-        """Create a `ChannelClosedError` instance.
+        """Initialize this error.
 
         Args:
-            channel: A reference to the channel that was closed.
+            channel: The channel that was closed.
         """
         super().__init__(f"Channel {channel} was closed", channel)

src/frequenz/channels/_merge.py

@@ -87,7 +87,7 @@ def merge(*receivers: Receiver[_T]) -> Merger[_T]:
             single stream.
 
     Raises:
-        ValueError: if no receivers are provided.
+        ValueError: If no receivers are provided.
     """
     if not receivers:
         raise ValueError("At least one receiver must be provided")
@@ -104,7 +104,7 @@ class Merger(Receiver[_T]):
     """
 
     def __init__(self, *receivers: Receiver[_T], name: str | None) -> None:
-        """Create a `Merger` instance.
+        """Initialize this merger.
 
         Args:
             *receivers: The receivers to merge.
@@ -122,13 +122,13 @@ def __init__(self, *receivers: Receiver[_T], name: str | None) -> None:
         self._results: deque[_T] = deque(maxlen=len(self._receivers))
 
     def __del__(self) -> None:
-        """Cleanup any pending tasks."""
+        """Finalize this merger."""
         for task in self._pending:
             if not task.done() and task.get_loop().is_running():
                 task.cancel()
 
     async def stop(self) -> None:
-        """Stop the `Merger` instance and cleanup any pending tasks."""
+        """Stop this merger."""
         for task in self._pending:
             task.cancel()
         await asyncio.gather(*self._pending, return_exceptions=True)
@@ -177,8 +177,8 @@ def consume(self) -> _T:
             The next value that was received.
 
         Raises:
-            ReceiverStoppedError: if the receiver stopped producing messages.
-            ReceiverError: if there is some problem with the receiver.
+            ReceiverStoppedError: If the receiver stopped producing messages.
+            ReceiverError: If there is some problem with the receiver.
         """
         if not self._results and not self._pending:
             raise ReceiverStoppedError(self)