DOC: Clarify docstrings, remove print statements

src/caosdb/apiutils.py

@@ -205,8 +205,9 @@ def compare_entities(old_entity: Entity, new_entity: Entity, compare_referenced_
         value that is stored in the respective entity.
 
     If `compare_referenced_records` is `True`, also referenced entities will be
-    compared using this function, but with `compare_referenced_records = False`
-    to prevent infinite recursion in case of circular references.
+    compared using this function (which is then called with
+    `compare_referenced_records = False` to prevent infinite recursion in case
+    of circular references).
 
     Parameters
     ----------
@@ -215,7 +216,9 @@ def compare_entities(old_entity: Entity, new_entity: Entity, compare_referenced_
     compare_referenced_records : bool, optional
         Whether to compare referenced records in case of both, `old_entity` and
         `new_entity`, have the same reference properties and both have a Record
-        object as value.
+        object as value. If set to `False`, only the corresponding Python
+        objects are compared which may lead to unexpected behavior when
+        identical records are stored in different objects. Default is False.
 
     """
     olddiff: Dict[str, Any] = {"properties": {}, "parents": []}
@@ -288,7 +291,7 @@ def compare_entities(old_entity: Entity, new_entity: Entity, compare_referenced_
                 if compare_referenced_records:
                     # scalar reference
                     if isinstance(prop.value, Entity) and isinstance(matching[0].value, Entity):
-                        # exlicitely not recursive to prevent infinite recursion
+                        # explicitely not recursive to prevent infinite recursion
                         same_value = empty_diff(
                             prop.value, matching[0].value, compare_referenced_records=False)
                     # list of references

unittests/test_apiutils.py

@@ -386,9 +386,6 @@ def test_wrong_merge_conflict_reference():
                        datatype=license_rt.name, value=license_rec_b)
     rec_b.add_property(name=doi_prop.name, value="https://doi.org/12345.678")
 
-    print(compare_entities(rec_a, rec_b))
-    print(compare_entities(license_rec_a, license_rec_b))
-    print(license_rec_b == license_rec_a)
     merge_entities(rec_a, rec_b)
     assert rec_a.get_property(license_rt.name) is not None
     assert rec_a.get_property(license_rt.name).value is not None
@@ -398,6 +395,12 @@ def test_wrong_merge_conflict_reference():
     assert rec_a.get_property("title").value == "Some dataset title"
     assert rec_a.get_property("doi").value == "https://doi.org/12345.678"
 
+    # Reset rec_a
+    rec_a = db.Record().add_parent(dataset_rt)
+    rec_a.add_property(name=license_rt.name,
+                       datatype=license_rt.name, value=license_rec_a)
+    rec_a.add_property(name=title_prop.name, value="Some dataset title")
+
     # this does not compare referenced records, so it will fail
     with pytest.raises(RuntimeError) as re:
         merge_entities(rec_a, rec_b, merge_references_with_empty_diffs=False)