Improve documentation of the frequenz.channels.experimental.Pipe

Documentation shows how to create Pipe inside context manager
to cleanup the resources when context is exited.

Author: ela-kotulska-frequenz

RELEASE_NOTES.md

@@ -7,6 +7,7 @@
 ## Upgrading
 
 - Some minimal dependencies have been bumped, so you might need to adjust your dependencies accordingly.
+- Improve documentation of the frequenz.channels.experimental.Pipe
 
 ## New Features
 

src/frequenz/channels/experimental/_pipe.py

@@ -25,17 +25,34 @@ class Pipe(typing.Generic[ChannelMessageT]):
 
     Example:
         ```python
+        from contextlib import asynccontextmanager
+        from typing import AsyncIterator
         from frequenz.channels import Broadcast, Pipe
 
-        channel1: Broadcast[int] = Broadcast(name="channel1")
-        channel2: Broadcast[int] = Broadcast(name="channel2")
-
-        receiver_chan1 = channel1.new_receiver()
-        sender_chan2 = channel2.new_sender()
-
-        async with Pipe(channel2.new_receiver(), channel1.new_sender()):
-            await sender_chan2.send(10)
-            assert await receiver_chan1.receive() == 10
+        @asynccontextmanager
+        async def create_forwarding_pipe(
+            receiver: Receiver[int],
+        ) -> AsyncIterator[Broadcast[int]]:
+            forwarding_channel: Broadcast[int] = Broadcast(name="forwarded channel")
+            forwarding_sender = forwarding_channel.new_sender()
+            try:
+                async with Pipe(receiver, forwarding_sender):
+                    yield forwarding_channel
+            finally:
+                receiver.close()
+                await forwarding_channel.close()
+
+        source_channel: Broadcast[int] = Broadcast(name="source channel")
+        source_sender = source_channel.new_sender()
+
+        # Create a pipe in a context manager to ensure the
+        # resources are cleaned up when the context is exited.
+        async with create_forwarding_pipe(
+            source_channel.new_receiver()
+        ) as forwarding_channel:
+            receiver = forwarding_channel.new_receiver()
+            await source_sender.send(10)
+            assert await receiver.receive() == 10
         ```
     """