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.

Signed-off-by: Elzbieta Kotulska <[email protected]>

Author: ela-kotulska-frequenz

RELEASE_NOTES.md

@@ -13,7 +13,8 @@
 
 ## New Features
 
-* Add a new `OptionalReceiver` class that wraps an optional underlying receiver, allowing for indefinite waiting when no receiver is set.
+- Add a new `OptionalReceiver` class that wraps an optional underlying receiver, allowing for indefinite waiting when no receiver is set.
+- Improve documentation of the `frequenz.channels.experimental.Pipe`
 
 ## Bug Fixes
 

src/frequenz/channels/experimental/_pipe.py

@@ -25,17 +25,27 @@ class Pipe(typing.Generic[ChannelMessageT]):
 
     Example:
         ```python
-        from frequenz.channels import Broadcast, Pipe
+        from contextlib import closing, aclosing, AsyncExitStack
+        from frequenz.channels import Broadcast, Pipe, Receiver
 
-        channel1: Broadcast[int] = Broadcast(name="channel1")
-        channel2: Broadcast[int] = Broadcast(name="channel2")
+        # Channels, receivers and Pipe are in AsyncExitStack
+        # to close and stop them at the end.
 
-        receiver_chan1 = channel1.new_receiver()
-        sender_chan2 = channel2.new_sender()
+        async with AsyncExitStack() as stack:
+            source_channel = await stack.enter_async_context(
+                aclosing(Broadcast(name="source channel")))
+            source_receiver = await stack.enter_async_context(
+                closing(source_channel.new_receiver()))
 
-        async with Pipe(channel2.new_receiver(), channel1.new_sender()):
-            await sender_chan2.send(10)
-            assert await receiver_chan1.receive() == 10
+            forwarding_channel = await stack.enter_async_context(
+                aclosing(Broadcast(name="forwarding channel")))
+            await stack.enter_async_context(Pipe(source_receiver, forwarding_channel.new_sender()))
+
+            receiver = await stack.enter_async_context(closing(forwarding_channel.new_receiver()))
+
+            source_sender = source_channel.new_sender()
+            await source_sender.send(10)
+            assert await receiver.receive() == 10
         ```
     """