Improve the _receiver module description

Give a general introduction to receivers, explaining how one usually
create them, how to map values, how to handle receiving errors and how
to use the low-level methods.

This module is not publicly available, so users won't be able to access
the information in IDEs for example, but it will be rendered as part of
the User Guide.

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

Author: llucax

src/frequenz/channels/_receiver.py

@@ -1,7 +1,136 @@
 # License: MIT
 # Copyright © 2022 Frequenz Energy-as-a-Service GmbH
 
-"""Channel receiver and associated exceptions."""
+"""Receiver interface and related exceptions.
+
+# Receivers
+
+Messages are received from [channels](/user-guide/channels/index.md) through
+[Receiver][frequenz.channels.Receiver] objects. [Receivers][frequenz.channels.Receiver]
+are usually created by calling `channel.new_receiver()` and are [async
+iterators][typing.AsyncIterator], so the easiest way to receive values from them as
+a stream is to use `async for`:
+
+```python
+from frequenz.channels import Anycast
+
+channel = Anycast[int](name="test-channel")
+receiver = channel.new_receiver()
+
+async for value in receiver:
+    print(value)
+```
+
+If you need to receive values in different places or expecting a particular
+sequence, you can use the [`receive()`][frequenz.channels.Receiver.receive] method:
+
+```python
+from frequenz.channels import Anycast
+
+channel = Anycast[int](name="test-channel")
+receiver = channel.new_receiver()
+
+first_value = await receiver.receive()
+print(f"First value: {first_value}")
+
+second_value = await receiver.receive()
+print(f"Second value: {second_value}")
+```
+
+# Value Transformation
+
+If you need to transform the received values, receivers provide a
+[`map()`][frequenz.channels.Receiver.map] method to easily do so:
+
+```python
+from frequenz.channels import Anycast
+
+channel = Anycast[int](name="test-channel")
+receiver = channel.new_receiver()
+
+async for value in receiver.map(lambda x: x + 1):
+    print(value)
+```
+
+[`map()`][frequenz.channels.Receiver.map] returns a new full receiver, so you can
+use it in any of the ways described above.
+
+# Error Handling
+
+!!! Tip inline end
+
+    For more information about handling errors, please refer to the
+    [Error Handling](/user-guide/error-handling/) section of the user guide.
+
+If there is an error while receiving a message,
+a [`ReceiverError`][frequenz.channels.ReceiverError] exception is raised for both
+[`receive()`][frequenz.channels.Receiver.receive] method and async iteration
+interface.
+
+If the receiver has completely stopped (for example the underlying channel was
+closed), a [`ReceiverStoppedError`][frequenz.channels.ReceiverStoppedError] exception
+is raised by [`receive()`][frequenz.channels.Receiver.receive] method.
+
+```python
+from frequenz.channels import Anycast
+
+channel = Anycast[int](name="test-channel")
+receiver = channel.new_receiver()
+
+try:
+    await receiver.receive()
+except ReceiverStoppedError as error:
+    print("The receiver was stopped")
+except ReceiverError as error:
+    print(f"There was an error trying to receive: {error}")
+```
+
+When used as an async iterator, the iteration will just stop without raising an
+exception:
+
+```python
+from frequenz.channels import Anycast
+
+channel = Anycast[int](name="test-channel")
+receiver = channel.new_receiver()
+
+try:
+    async for value in receiver:
+        print(value)
+except ReceiverStoppedError as error:
+    print("Will never happen")
+except ReceiverError as error:
+    print(f"There was an error trying to receive: {error}")
+# If we get here, the receiver was stopped
+```
+
+# Advanced Usage
+
+!!! Warning inline end
+
+    This section is intended for library developers that want to build other low-level
+    abstractions on top of channels. If you are just using channels, you can safely
+    ignore this section.
+
+Receivers extend on the [async iterator protocol][typing.AsyncIterator] by providing
+a [`ready()`][frequenz.channels.Receiver.ready] and
+a [`consume()`][frequenz.channels.Receiver.consume] method.
+
+The [`ready()`][frequenz.channels.Receiver.ready] method is used to await until the
+receiver has a new value available, but without actually consuming it. The
+[`consume()`][frequenz.channels.Receiver.consume] method consumes the next available
+value and returns it.
+
+[`ready()`][frequenz.channels.Receiver.ready] can be called multiple times, and it
+will return immediately if the receiver is already ready.
+[`consume()`][frequenz.channels.Receiver.consume] must be called only after
+[`ready()`][frequenz.channels.Receiver.ready] is done and only once, until the next
+call to [`ready()`][frequenz.channels.Receiver.ready].
+
+Exceptions are never raised by [`ready()`][frequenz.channels.Receiver.ready], they
+are always delayed until [`consume()`][frequenz.channels.Receiver.consume] is
+called.
+"""
 
 from __future__ import annotations
 
@@ -16,7 +145,7 @@
 
 
 class Receiver(ABC, Generic[_T]):
-    """A channel Receiver."""
+    """An endpoint to receive messages."""
 
     async def __anext__(self) -> _T:
         """Await the next value in the async iteration over received values.