Mercurial > hg > ucx / changeset

--- a/docs/Writerside/topics/list.h.md	Tue Mar 04 18:20:36 2025 +0100
+++ b/docs/Writerside/topics/list.h.md	Wed Mar 05 20:53:41 2025 +0100
@@ -128,9 +128,16 @@
 int cxListCompare(const CxList *list, const CxList *other);
 ```
 
-<warning>
-TODO: add documentation
-</warning>
+Arbitrary lists can be compared item-wise with `cxListCompare()`, as long as the compare functions of both lists are equivalent.
+
+That means, you can compare an UCX [array list](array_list.h.md) with a [linked list](linked_list.h.md),
+and you could even compare lists that are storing pointers with lists that are not storing pointers.
+
+However, the optimized list-internal compare implementation is only used, when both the compare functions and the list classes are identical.
+Otherwise, `cxListCompare()` will behave as if you were iterating through both lists and manually comparing the items.
+
+The return value of `cxListCompare()` is zero, if the lists are item-wise equivalent.
+If they are not, the non-zero return value equals the return value of the used compare function for the first pair of elements that are not equal. 
 
 ## Dispose
 
@@ -138,9 +145,15 @@
 void cxListFree(CxList *list);
 ```
 
-<warning>
-TODO: add documentation
-</warning>
+No matter with which function a `CxList` has been created, you can _always_ deallocate the entire memory with a call to `cxListFree()`.
+
+The effect is equivalent to invoking `cxListClear()` plus deallocating the memory for the list structure.
+That means, for each item in the list, the destructor functions defined by `cxDefineDestructor()` or `cxDefineAdvancedDestructor()` are called,
+before deallocating the list.
+
+When the list has been storing pointers, make sure that either another reference to the same memory exist in your program,
+or any of the destructor functions deallocates the memory.
+Otherwise, there is a risk of a memory leak.
 
 ## Implement own List Structures