filter: Reword docstring to explain what the element does278-filter-documentation-could-be-better

The docstring included instructions on what it *should* be used for,
which is unnecessary.

Further, it was vague on what the element actually did. The new
docstring should be more explicit on what it does.

1 files changed, 9 insertions, 8 deletions

diff --git a/buildstream/plugins/elements/filter.py b/buildstream/plugins/elements/filter.py
index 672b801ce..2487a9799 100644
--- a/buildstream/plugins/elements/filter.py
+++ b/buildstream/plugins/elements/filter.py
@@ -20,16 +20,17 @@
 
 """Filter element
 
-This element copies a subset of the files in its dependencies.
+This filters another element by producing an output that is a subset of
+the filtered element.
 
-This is normally used to separate out the contents of an artifact
-into multiple artifacts and define separate sets of dependencies,
-in cases where a build produces multiple discrete "packages",
-e.g. systemd and udev; gettext and libintl.
+To specify the element to filter, specify it as the one and only build
+dependency to filter. See :ref:`Dependencies <format_dependencies>`
+for what dependencies are and how to specify them.
 
-This element expects precisely one build dependency, and multiple
-runtime dependencies that are not the element that was the build
-dependency.
+Dependencies aside from the filtered element may be specified, but
+they must be runtime dependencies only. This can be useful to propagate
+runtime dependencies forward from this filter element onto its reverse
+dependencies.
 
 The default configuration and possible options are as such:
   .. literalinclude:: ../../../buildstream/plugins/elements/filter.yaml