DOC: more docstrings for the sync_graph

src/caoscrawler/sync_graph.py

@@ -140,8 +140,14 @@ class SyncGraph():
 
     def __init__(self, entities: list[db.Entity], identifiableAdapter: IdentifiableAdapter):
         self.identifiableAdapter = identifiableAdapter
+        # A dictionary allowing for quick lookup of sync nodes using their (possibly negative) IDs.
+        # This dictionary is initially set using _mark_entities_with_path_or_id and later updated
+        # using set_id_of_node.
         self._id_look_up: dict[Union[int, TempID, str], SyncNode] = {}
+        # Similar as above for looking up nodes using paths:
         self._path_look_up: dict[str, SyncNode] = {}
+        # Similar as above for looking up nodes using identifiables. This dictionary uses
+        # the get_representation method of Identifiable as keys.
         self._identifiable_look_up: dict[str, SyncNode] = {}
         self._missing: dict[int, SyncNode] = {}
         self._existing: dict[int, SyncNode] = {}
@@ -179,8 +185,14 @@ class SyncGraph():
             self.identifiableAdapter.check_identifying_props(node)
 
     def set_id_of_node(self, node: SyncNode, node_id: Optional[str] = None):
-        """sets the ID attribute of the given SyncNode. If node_id is None, a negative Id will be
-        given indicating that the node does not exist on the remote server"""
+        """sets the ID attribute of the given SyncNode to node_id.
+
+        If node_id is None, a negative ID will be
+        given indicating that the node does not exist on the remote server.
+        Furthermore it will be marked as missing using _mark_missing.
+
+        Last review by Alexander Schlemmer on 2024-05-24.
+        """
         if node.id is not None:
             raise RuntimeError('Cannot update ID.\n'
                                f'It already is {node.id} and shall be set to {node_id}.')