# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1741204421 -3600
# Node ID 26299ce9c955141bc6cc4ce7ad1ff580d1dfe05a
# Parent  5cba456aff67e45576c3553ef7eb151d55d8cc8c
documentation for list compare and dispose

relates to #451

diff -r 5cba456aff67 -r 26299ce9c955 docs/Writerside/topics/list.h.md
--- 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