DOC: more comments and docstrings in sync_graph

src/caoscrawler/sync_graph.py

@@ -335,6 +335,9 @@ class SyncGraph():
 
     @staticmethod
     def _sanity_check(entities: list[db.Entity]):
+        """
+        Checks whether each record in entities has at least one parent.
+        """
         for ent in entities:
             if ent.role == "Record" and len(ent.parents) == 0:
                 raise RuntimeError(f"Records must have a parent.\n{ent}")
@@ -573,6 +576,8 @@ class SyncGraph():
         self._sanity_check(entities)
         entities = self._create_flat_list(entities)
         se_lookup: dict[int, SyncNode] = {}  # lookup: python id -> SyncNode
+
+        #
         for el in entities:
             self.nodes.append(SyncNode(
                 el,
@@ -585,6 +590,10 @@ class SyncGraph():
                                    value=lambda val: se_lookup[id(val)])
 
     def _mark_missing(self, node: SyncNode):
+        """Mark a sync node as missing and remove it from the dictionary of unchecked nodes.
+
+        Last review by Alexander Schlemmer on 2024-05-24.
+        """
         self._missing[id(node)] = node
         self.unchecked.remove(node)
 
@@ -592,7 +601,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(node):
             if self._identifiable_is_needed(other_node):
                 self._set_identifiable_of_node(other_node)
@@ -603,6 +612,10 @@ class SyncGraph():
                 self.set_id_of_node(other_node)
 
     def _mark_existing(self, node: SyncNode):
+        """Mark a sync node as existing and remove it from the dictionary of unchecked nodes.
+
+        Last review by Alexander Schlemmer on 2024-05-24.
+        """
         if isinstance(node.id, TempID):
             raise ValueError("ID must valid existing entities, not TempID")
         self._existing[id(node)] = node
@@ -611,7 +624,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(node):
             if self._identifiable_is_needed(other_node):
                 self._set_identifiable_of_node(other_node)