Improve the _exceptions module description

Explain the base exceptions and the basics of error handling, including
how to get the cause of an exception.

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/_exceptions.py

@@ -1,7 +1,70 @@
 # License: MIT
 # Copyright © 2022 Frequenz Energy-as-a-Service GmbH
 
-"""Base exception classes."""
+"""Base exception classes.
+
+# Exceptions
+
+All exceptions generated by this library inherit from the
+[`Error`][frequenz.channels.Error] exception.
+
+Exceptions generated by channels inherit from the
+[`ChannelError`][frequenz.channels.ChannelError] exception. When there is an attempt to
+use a closed channel, a [`ChannelClosedError`][frequenz.channels.ChannelClosedError]
+exception is raised.
+
+# Causes
+
+When a exception is caused by another exception, for example if the underlying channel
+was closed while seding or receiving a message, the original exception will be
+available as the cause of the exception:
+
+```python
+from frequenz.channels import Anycast, ChannelClosedError, SenderError
+
+channel = Anycast[int](name="test-channel")
+sender = channel.new_sender()
+
+try:
+    await sender.send(42)
+except SenderError as error:
+    match error.__cause__:
+        case None:
+            print("The message couldn't be sent for an known reason")
+        case ChannelClosedError() as closed_error:
+            print(f"The message couldn't be sent, channel closed: {closed_error}")
+        case _ as unknown_error:
+            print(f"The message couldn't be sent: {unknown_error}")
+```
+
+Tip:
+    If you are using the async iteration interface for receivers, then you can
+    access the cause of the
+    [`ReceiverStoppedError`][frequenz.channels.ReceiverStoppedError] exception by
+    explicitly calling [`receive()`][frequenz.channels.Receiver.receive] on the
+    receiver after the iteration is done:
+
+    ```python
+    from frequenz.channels import Anycast, ChannelClosedError, ReceiverStoppedError
+
+    channel = Anycast[int](name="test-channel")
+    receiver = channel.new_receiver()
+
+    async for value in receiver:
+        print(value)
+    try:
+        await receiver.receive()
+    except ReceiverStoppedError as error:
+        print("The receiver was stopped")
+        match error.__cause__:
+            case None:
+                print("The receiver was stopped without a known reason")
+            case ChannelClosedError() as closed_error:
+                print(f"The channel was closed with error: {closed_error}")
+            case _ as unknown_error:
+                print(f"The receiver was stopped due to an unknown error: {unknown_error}")
+    ```
+"""
 
 from typing import Any