Include TODO/notes to open tickets.

src/python/pants/engine/build_files.py

@@ -319,7 +319,8 @@ def _recursive_dirname(f):
 
 
 # TODO: This is a bit of a lie: `Struct` is effectively abstract, so this collection
-# will contain subclasses of `Struct` for the symbol table types.
+# will contain subclasses of `Struct` for the symbol table types. These APIs need more
+# polish before we make them public: see #4535 in particular.
 HydratedStructs = Collection.of(Struct)
 
 

src/python/pants/engine/legacy/source_mapper.py

@@ -53,7 +53,8 @@ def target_addresses_for_source(self, source):
   def _match_sources(self, sources_set, fileset):
     # NB: Deleted files can only be matched against the 'filespec' (ie, `PathGlobs`) for a target,
     # so we don't actually call `fileset.matches` here.
-    # TODO: This call should be pushed down into the engine one way or another.
+    # TODO: This call should be pushed down into the engine to match directly against
+    # `PathGlobs` as we erode the `AddressMapper`/`SourceMapper` split.
     return any_matches_filespec(sources_set, fileset.filespec)
 
   def _owns_any_source(self, sources_set, legacy_target):

src/python/pants/scm/change_calculator.py

@@ -145,13 +145,14 @@ def iter_changed_target_addresses(self, changed_request):
       return
 
     # For dependee finding, we need to parse all build files to collect all structs. But we
-    # don't need to fully hydrate targets (ie, expand their source globs).
+    # don't need to fully hydrate targets (ie, expand their source globs), and so we use
+    # the `HydratedStructs` product. See #4535 for more info.
     adaptor_iter = (t
                     for targets in self._scheduler.product_request(HydratedStructs,
                                                                    [DescendantAddresses('')])
                     for t in targets.dependencies)
     graph = _DependentGraph.from_iterable(target_types_from_symbol_table(self._symbol_table),
-                                                        adaptor_iter)
+                                          adaptor_iter)
 
     if changed_request.include_dependees == 'direct':
       for address in graph.dependents_of_addresses(changed_addresses):