Improves the documentation on Receiver.filter (frequenz-floss#313)

This also adds a new section to the documentation explaining how to
filter to the user guide.

Author: llucax

RELEASE_NOTES.md

@@ -2,16 +2,4 @@
 
 ## Summary
 
-<!-- Here goes a general summary of what this release is about -->
-
-## Upgrading
-
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
-
-## New Features
-
-<!-- Here goes the main new features and examples or instructions on how to use them -->
-
-## Bug Fixes
-
-<!-- Here goes notable bug fixes that are worth a special mention or explanation -->
+This release improves the documentation on `Receiver.filter`.

docs/_scripts/macros.py

@@ -6,8 +6,7 @@
 from typing import Any
 
 import markdown as md
-from griffe import Object
-from griffe.collections import ModulesCollection
+from griffe import ModulesCollection, Object
 from markdown.extensions import toc
 from mkdocs_macros import plugin as macros
 from mkdocstrings_handlers.python.handler import PythonHandler

src/frequenz/channels/_receiver.py

@@ -55,6 +55,25 @@
 [`map()`][frequenz.channels.Receiver.map] returns a new full receiver, so you can
 use it in any of the ways described above.
 
+# Message Filtering
+
+If you need to filter the received messages, receivers provide a
+[`filter()`][frequenz.channels.Receiver.filter] method to easily do so:
+
+```python show_lines="6:"
+from frequenz.channels import Anycast
+
+channel = Anycast[int](name="test-channel")
+receiver = channel.new_receiver()
+
+async for message in receiver.filter(lambda x: x % 2 == 0):
+    print(message)  # Only even numbers will be printed
+```
+
+As with [`map()`][frequenz.channels.Receiver.map],
+[`filter()`][frequenz.channels.Receiver.filter] returns a new full receiver, so you can
+use it in any of the ways described above.
+
 # Error Handling
 
 !!! Tip inline end
@@ -254,10 +273,11 @@ def filter(
             original receiver and use that instead.
 
         Args:
-            filter_function: The function to be applied on incoming messages.
+            filter_function: The function to be applied on incoming messages to
+                determine if they should be received.
 
         Returns:
-            A new receiver that applies the function on the received messages.
+            A new receiver that only receives messages that pass the filter.
         """
         return _Filter(receiver=self, filter_function=filter_function)