DOC: added docstring for function compare entities

src/caosdb/apiutils.py

@@ -561,7 +561,23 @@ def getCommitIn(folder):
 COMPARED = ["name", "role", "datatype", "description", "importance"]
 
 
-def compare_entities(old_entity, new_entity):
+def compare_entities(old_entity: Entity, new_entity: Entity):
+    """
+    Compare two entites.
+
+    Return a tuple of dictionaries, the first index belongs to additional information for old
+    entity, the second index belongs to additional information for new entity.
+
+    Additional information means in detail:
+    - Additional parents (a list under key "parents")
+    - Information about properties:
+      - Each property lists either an additional property or a property with a changed:
+        - ... datatype
+        - ... importance or
+        - ... value (not implemented yet)
+        In case of changed information the value listed under the respective key shows the
+        value that is stored in the respective entity.
+    """
     olddiff = {"properties": {}, "parents": []}
     newdiff = {"properties": {}, "parents": []}