filter.py/filter.yaml: Documentation improvements

2 files changed, 22 insertions, 21 deletions

diff --git a/buildstream/plugins/elements/filter.py b/buildstream/plugins/elements/filter.py
index b2c292261..b8b9c749d 100644
--- a/buildstream/plugins/elements/filter.py
+++ b/buildstream/plugins/elements/filter.py
@@ -20,21 +20,21 @@
 """
 filter - Extract a subset of files from another element
 =======================================================
-This filters another element by producing an output that is a subset of
-the filtered element.
-
-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.
-
-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.
-
-When workspaces are opened, closed or reset on this element, or this
-element is tracked, instead of erroring due to a lack of sources, this
-element will transparently pass on the command to its sole build-dependency.
+Filter another element by producing an output that is a subset of
+the parent element's output. Subsets are defined by the parent element's
+:ref:`split rules <public_split_rules>`.
+
+Overview
+--------
+A filter element must have exactly one *build* dependency, where said
+dependency is the 'parent' element which we would like to filter.
+Runtime dependencies may also be specified, which can be useful to propagate
+forward from this filter element onto its reverse dependencies.
+See :ref:`Dependencies <format_dependencies>` to see how we specify dependencies.
+
+When workspaces are opened, closed or reset on a filter element, or this
+element is tracked, the filter element will transparently pass on the command
+to its parent element (the sole build-dependency).
 
 The default configuration and possible options are as such:
   .. literalinclude:: ../../../buildstream/plugins/elements/filter.yaml
diff --git a/buildstream/plugins/elements/filter.yaml b/buildstream/plugins/elements/filter.yaml
index 627a00cce..78465a183 100644
--- a/buildstream/plugins/elements/filter.yaml
+++ b/buildstream/plugins/elements/filter.yaml
@@ -2,20 +2,21 @@
 # Filter element configuration
 config:
 
-  # A list of domains to include from each artifact, as
-  # they were defined in the element's 'split-rules'.
+  # A list of domains to include in each artifact, as
+  # they were defined as public data in the parent
+  # element's 'split-rules'.
   #
   # Since domains can be added, it is not an error to
   # specify domains which may not exist for all of the
   # elements in this composition.
   #
   # The default empty list indicates that all domains
-  # from each dependency should be included.
+  # of the parent's artifact should be included.
   #
   include: []
 
   # A list of domains to exclude from each artifact, as
-  # they were defined in the element's 'split-rules'.
+  # they were defined in the parent element's 'split-rules'.
   #
   # In the case that a file is spoken for by a domain
   # in the 'include' list and another in the 'exclude'
@@ -23,7 +24,7 @@ config:
   exclude: []
 
   # Whether to include orphan files which are not
-  # included by any of the 'split-rules' present on
-  # a given element.
+  # included by any of the 'split-rules' present in
+  # the parent element.
   #
   include-orphans: False