Element dependencies: Improve inline documentation to make it clear that deps of _Scope.BUILD don't return self

src/buildstream/element.py

@@ -72,7 +72,7 @@
 from itertools import chain
 import string
 from threading import Lock
-from typing import cast, TYPE_CHECKING, Dict, Iterator, Iterable, List, Optional, Set, Sequence
+from typing import cast, TYPE_CHECKING, Dict, Iterator, Iterable, List, Optional, Set, Sequence, Generator
 
 from pyroaring import BitMap  # pylint: disable=no-name-in-module
 
@@ -883,8 +883,8 @@ def _dependencies(self, scope: _Scope, *, recurse=True, visited=None):
                         yield dep
         else:
 
-            def visit(element, scope, visited):
-                if scope == _Scope.ALL:
+            def visit(element: Element, scope: _Scope, visited: tuple[BitMap,BitMap]) -> Generator[Element]:
+                if scope == _Scope.ALL: # The element, it's runtime and build dependencies
                     visited[0].add(element._unique_id)
                     visited[1].add(element._unique_id)
 
@@ -893,22 +893,22 @@ def visit(element, scope, visited):
                             yield from visit(dep, _Scope.ALL, visited)
 
                     yield element
-                elif scope == _Scope.BUILD:
+                elif scope == _Scope.BUILD: # The element's build dependencies only
                     visited[0].add(element._unique_id)
 
                     for dep in element.__build_dependencies:
                         if dep._unique_id not in visited[1]:
                             yield from visit(dep, _Scope.RUN, visited)
-
-                elif scope == _Scope.RUN:
+                    # _Scope.BUILD intentionally excludes yielding the element itself.
+                elif scope == _Scope.RUN: # The element and it's runtime dependencies
                     visited[1].add(element._unique_id)
 
                     for dep in element.__runtime_dependencies:
                         if dep._unique_id not in visited[1]:
                             yield from visit(dep, _Scope.RUN, visited)
 
                     yield element
-                else:
+                else: # _Scope.NONE: Only the element
                     yield element
 
             if visited is None: