docs: Improve formatting of some symbols

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

Author: llucax

src/frequenz/channels/anycast.py

@@ -171,7 +171,7 @@ async def receive(self) -> Optional[T]:
         will receive each message.
 
         Returns:
-            None, if the channel is closed, a message otherwise.
+            `None`, if the channel is closed, a message otherwise.
         """
         while len(self._chan.deque) == 0:
             if self._chan.closed:

src/frequenz/channels/base_classes.py

@@ -36,14 +36,14 @@ async def receive(self) -> Optional[T]:
         """Receive a message from the channel.
 
         Returns:
-            None, if the channel is closed, a message otherwise.
+            `None`, if the channel is closed, a message otherwise.
         """
 
     def __aiter__(self) -> Receiver[T]:
         """Initialize the async iterator over received values.
 
         Returns:
-            self, since no extra setup is needed for the iterator
+            `self`, since no extra setup is needed for the iterator.
         """
         return self
 
@@ -69,7 +69,7 @@ def map(self, call: Callable[[T], U]) -> Receiver[U]:
             call: function to apply on incoming messages.
 
         Returns:
-            A receiver to read results of the given function from.
+            A `Receiver` to read results of the given function from.
         """
         return _Map(self, call)
 
@@ -123,7 +123,8 @@ def enqueue(self, msg: T) -> None:
 class _Map(Receiver[U], Generic[T, U]):
     """Apply a transform function on a channel receiver.
 
-    Has two generic types -
+    Has two generic types:
+
     - The input type: value type in the input receiver.
     - The output type: return type of the transform method.
     """
@@ -143,7 +144,7 @@ async def receive(self) -> Optional[U]:
         """Return a transformed message received from the input channel.
 
         Returns:
-            None, if the channel is closed, a message otherwise.
+            `None`, if the channel is closed, a message otherwise.
         """
         msg = await self._recv.receive()
         if msg is None:

src/frequenz/channels/bidirectional.py

@@ -47,7 +47,7 @@ def client_handle(self) -> BidirectionalHandle[T, U]:
 
     @property
     def service_handle(self) -> BidirectionalHandle[U, T]:
-        """Get a BidirectionalHandle for the service to use.
+        """Get a `BidirectionalHandle` for the service to use.
 
         Returns:
             Object to send/receive messages with.
@@ -86,6 +86,6 @@ async def receive(self) -> Optional[U]:
         """Receive a value from the other side.
 
         Returns:
-            Received value, or None if the channels are closed.
+            Received value, or `None` if the channels are closed.
         """
         return await self._receiver.receive()

src/frequenz/channels/broadcast.py

@@ -22,7 +22,7 @@
 class Broadcast(Generic[T]):
     """A channel to broadcast messages to multiple receivers.
 
-    Broadcast channels can have multiple senders and multiple receivers. Each
+    `Broadcast` channels can have multiple senders and multiple receivers. Each
     message sent through any of the senders is received by all of the
     receivers.
 
@@ -272,7 +272,7 @@ async def receive(self) -> Optional[T]:
             EOFError: when the receiver has been converted into a `Peekable`.
 
         Returns:
-            None, if the channel is closed, a message otherwise.
+            `None`, if the channel is closed, a message otherwise.
         """
         if not self._active:
             raise EOFError("This receiver is no longer active.")

src/frequenz/channels/select.py

@@ -36,7 +36,7 @@ class Select:
     messages coming in the additional async iterators are dropped, and
     a warning message is logged.
 
-    [Receiver][frequenz.channels.Receiver]s also function as AsyncIterator.
+    [Receiver][frequenz.channels.Receiver]s also function as `AsyncIterator`.
 
     Example:
         For example, if there are two async iterators that you want to
@@ -86,8 +86,8 @@ def __del__(self) -> None:
     async def ready(self) -> bool:
         """Wait until there is a message in any of the async iterators.
 
-        Returns True if there is a message available, and False if all async
-        iterators have closed.
+        Returns `True` if there is a message available, and `False` if all
+        async iterators have closed.
 
         Returns:
             Boolean indicating whether there are further messages or not.
@@ -138,17 +138,17 @@ async def ready(self) -> bool:
         return True
 
     def __getattr__(self, name: str) -> Optional[Any]:
-        """Return the latest unread message from a AsyncIterator, if available.
+        """Return the latest unread message from a `AsyncIterator`, if available.
 
         Args:
             name: Name of the channel.
 
         Returns:
-            Latest unread message for the specified AsyncIterator, or None.
+            Latest unread message for the specified `AsyncIterator`, or `None`.
 
         Raises:
-            KeyError: when the name was not specified when creating the Select
-                instance.
+            KeyError: when the name was not specified when creating the
+                `Select` instance.
         """
         result = self._result[name]
         if result is None:

src/frequenz/channels/utils/timer.py

@@ -70,7 +70,7 @@ def stop(self) -> None:
 
         Once `stop` has been called, all subsequent calls to
         [receive()][frequenz.channels.Timer.receive] will immediately return
-        None.
+        `None`.
         """
         self._stopped = True