diff -r 03bbdf402675 -r feab7c1e80d4 docs/Writerside/topics/compare.h.md
--- a/docs/Writerside/topics/compare.h.md	Thu Feb 06 20:09:55 2025 +0100
+++ b/docs/Writerside/topics/compare.h.md	Thu Feb 06 20:26:31 2025 +0100
@@ -1,43 +1,77 @@
 # Compare Functions
 
-<warning>
-Outdated - Rewrite!
-</warning>
+The `compare.h` header file contains a collection of compare functions for various primitive types.
+
+They come in two flavors:
+- prefixed with `cx_vcmp` they are taking the values directly as arguments
+- prefixed with `cx_cmp` the signature is designed to be compatible with the `cx_compare_func` function pointer type.
+
+## Examples
+
+In the following example we use `cx_cmp_int32` as compare function for a `CxList` of `int32_t` values.
 
-This header file contains a collection of compare functions for various data types.
-Their signatures are designed to be compatible with the `cx_compare_func` function pointer type.
+```C
+CxList *list = cxArrayListCreate(
+    cxDefaultAllocator, // use the default stdlib allocator
+    cx_cmp_int32,       // the compare function for the elements
+    sizeof(int32_t),    // the size of one element
+    256                 // reseve space for 256 elements
+);
+```
+
+In the next example we simply want to compare two `double` values with rounding tolerance.
+Note how the use of the `cx_vcmp` flavour makes it unnecessary to store the literal in a variable just to be able to take an address.
+```C
+double x = ...
+
+if (0 == cx_vcmp(x, 47.11)) {
+   // do something when equal (except tolerance)
+}
+```
+
+## List of Functions
 
-## Undocumented Symbols (TODO)
-### cx_cmp_double
-### cx_cmp_float
-### cx_cmp_int
-### cx_cmp_int16
-### cx_cmp_int32
-### cx_cmp_int64
-### cx_cmp_intptr
-### cx_cmp_longint
-### cx_cmp_longlong
-### cx_cmp_ptr
-### cx_cmp_uint
-### cx_cmp_uint16
-### cx_cmp_uint32
-### cx_cmp_uint64
-### cx_cmp_uintptr
-### cx_cmp_ulongint
-### cx_cmp_ulonglong
-### cx_vcmp_double
-### cx_vcmp_float
-### cx_vcmp_int
-### cx_vcmp_int16
-### cx_vcmp_int32
-### cx_vcmp_int64
-### cx_vcmp_intptr
-### cx_vcmp_longint
-### cx_vcmp_longlong
-### cx_vcmp_uint
-### cx_vcmp_uint16
-### cx_vcmp_uint32
-### cx_vcmp_uint64
-### cx_vcmp_uintptr
-### cx_vcmp_ulongint
-### cx_vcmp_ulonglong
+```C
+// Value Flavour
+cx_vcmp_double
+cx_vcmp_float
+cx_vcmp_int
+cx_vcmp_int16
+cx_vcmp_int32
+cx_vcmp_int64
+cx_vcmp_intptr
+cx_vcmp_longint
+cx_vcmp_longlong
+cx_vcmp_uint
+cx_vcmp_uint16
+cx_vcmp_uint32
+cx_vcmp_uint64
+cx_vcmp_uintptr
+cx_vcmp_ulongint
+cx_vcmp_ulonglong
+
+// Pointer Flavour
+cx_cmp_double
+cx_cmp_float
+cx_cmp_int
+cx_cmp_int16
+cx_cmp_int32
+cx_cmp_int64
+cx_cmp_intptr
+cx_cmp_longint
+cx_cmp_longlong
+cx_cmp_ptr
+cx_cmp_uint
+cx_cmp_uint16
+cx_cmp_uint32
+cx_cmp_uint64
+cx_cmp_uintptr
+cx_cmp_ulongint
+cx_cmp_ulonglong
+```
+
+<seealso>
+<category ref="apidoc">
+<a href="https://ucx.sourceforge.io/api/compare_8h.html">compare.h</a>
+</category>
+</seealso>