docs: Make some minor improvements

A few comments are rephrased or added or removed in the hopes to make
the documentation more reable or easier to understand.

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

Author: llucax

src/frequenz/channels/base_classes.py

@@ -13,7 +13,7 @@
 
 
 class Sender(ABC, Generic[T]):
-    """A base class for channel Sender."""
+    """A channel Sender."""
 
     @abstractmethod
     async def send(self, msg: T) -> bool:
@@ -29,7 +29,7 @@ async def send(self, msg: T) -> bool:
 
 
 class Receiver(ABC, Generic[T]):
-    """A base class for channel Receiver."""
+    """A channel Receiver."""
 
     @abstractmethod
     async def receive(self) -> Optional[T]:
@@ -79,10 +79,6 @@ def into_peekable(self) -> Peekable[T]:
         Once this function has been called, the receiver will no longer be
         usable, and calling `receive` on the receiver will raise an exception.
 
-        This is a default implementation of `into_peekable` that always raises
-        an exception.  This method can be overridden in other implementations
-        of `Receiver.`
-
         Raises:
             NotImplementedError: when a `Receiver` implementation doesn't have
                 a custom `get_peekable` implementation.
@@ -91,7 +87,7 @@ def into_peekable(self) -> Peekable[T]:
 
 
 class Peekable(ABC, Generic[T]):
-    """A base class for creating Peekables for peeking into channels.
+    """A channel peekable.
 
     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
@@ -109,7 +105,7 @@ def peek(self) -> Optional[T]:
 
 
 class BufferedReceiver(Receiver[T]):
-    """A base class for buffered channel receivers."""
+    """A channel receiver with a buffer."""
 
     @abstractmethod
     def enqueue(self, msg: T) -> None:

src/frequenz/channels/bidirectional.py

@@ -78,7 +78,7 @@ async def send(self, msg: T) -> bool:
             msg: The value to send.
 
         Returns:
-            Boolean indicating whether the send was successful.
+            Whether the send was successful or not.
         """
         return await self._sender.send(msg)
 

src/frequenz/channels/broadcast.py

@@ -181,8 +181,8 @@ async def send(self, msg: T) -> bool:
             msg: The message to be broadcast.
 
         Returns:
-            Boolean indicating whether the message was sent, based on whether
-            the broadcast channel is open or not.
+            Whether the message was sent, based on whether the broadcast
+                channel is open or not.
         """
         if self._chan.closed:
             return False

src/frequenz/channels/select.py

@@ -90,7 +90,7 @@ async def ready(self) -> bool:
         async iterators have closed.
 
         Returns:
-            Boolean indicating whether there are further messages or not.
+            Whether there are further messages or not.
         """
         if self._ready_count > 0:
             if self._ready_count == self._prev_ready_count:

src/frequenz/channels/utils/file_watcher.py

@@ -21,7 +21,7 @@ class EventType(Enum):
 
 
 class FileWatcher(Receiver[pathlib.Path]):
-    """A channel receiver that watches for file events using watchfiles."""
+    """A channel receiver that watches for file events."""
 
     def __init__(
         self,
@@ -32,9 +32,8 @@ def __init__(
 
         Args:
             paths: Paths to watch for changes.
-            event_types: Types of events to watch for.  Available types are:
-                CREATE, MODIFY, DELETE.  By default, watcher will watch for all
-                types of events.
+            event_types: Types of events to watch for or `None` to watch for
+                all event types.
         """
         if event_types is None:
             event_types = {EventType.CREATE, EventType.MODIFY, EventType.DELETE}

src/frequenz/channels/utils/timer.py

@@ -52,7 +52,7 @@ class Timer(Receiver[datetime]):
     """
 
     def __init__(self, interval: float) -> None:
-        """Create a `LocalTimer` instance.
+        """Create a `Timer` instance.
 
         Args:
             interval: number of seconds between messages.