DOC: more comments in sync_graph

src/caoscrawler/sync_graph.py

@@ -217,6 +217,8 @@ class SyncGraph():
         Since the result is returned in form of two lists, one with Entities that have a valid ID
         one with those that haven't, an error is raised if there are any SyncNodes without an
         (possibly negative) ID.
+
+        Last review by Alexander Schlemmer on 2024-05-24.
         """
         # TODO reactivate once the implementation is appropriate
         # if len(self.unchecked) > 1:
@@ -472,7 +474,10 @@ class SyncGraph():
 
     def _remove_non_identifiables(self):
         """ A path or an ID is sufficiently identifying. Thus, those entities can be marked as
-        checked """
+        checked
+
+        Last review by Alexander Schlemmer on 2024-05-24.
+        """
         for node in list(self.nodes[::-1]):
             if "nonidentifiable" in [p.name for p in node.registered_identifiable.properties]:
                 self.unchecked.remove(node)
@@ -569,7 +574,7 @@ class SyncGraph():
         # - mark existing
         # - mark missing
         # - merge
-        # For each dependend node, we check whether this allows to create an identifiable
+        # For each dependent node, we check whether this allows to create an identifiable
         for other_node in self._get_nodes_whose_identity_relies_on(target):
             if self._identifiable_is_needed(other_node):
                 self._set_identifiable_of_node(other_node)
@@ -593,14 +598,16 @@ class SyncGraph():
         entities = self._create_flat_list(entities)
         se_lookup: dict[int, SyncNode] = {}  # lookup: python id -> SyncNode
 
-        #
+        # Create new sync nodes from the list of entities, their registered identifiables
+        # are set from the identifiable adapter.
         for el in entities:
             self.nodes.append(SyncNode(
                 el,
                 self.identifiableAdapter.get_registered_identifiable(el)))
             se_lookup[id(el)] = self.nodes[-1]
+
+        # replace db.Entity objects with SyncNodes in references:
         for node in self.nodes:
-            # replace db.Entity objects with SyncNodes in references
             _set_each_scalar_value(node,
                                    condition=lambda val: id(val) in se_lookup,
                                    value=lambda val: se_lookup[id(val)])
@@ -621,7 +628,8 @@ class SyncGraph():
         for other_node in self._get_nodes_whose_identity_relies_on(node):
             if self._identifiable_is_needed(other_node):
                 self._set_identifiable_of_node(other_node)
-        # For each dependend node, we set the ID to None (missing)
+        # For each dependent node, we set the ID to None (missing)
+        # (None is the default second argument of set_id_of_node.)
         for other_node in self._get_nodes_whose_identity_relies_on(node):
             if other_node in self.unchecked:
                 print(f"set\n{other_node}\n to missing due to missing\n{node}")