diff -r f392f27a1dc6 -r 5cba456aff67 docs/Writerside/topics/list.h.md
--- a/docs/Writerside/topics/list.h.md Mon Mar 03 21:41:59 2025 +0100
+++ b/docs/Writerside/topics/list.h.md Tue Mar 04 18:20:36 2025 +0100
@@ -8,13 +8,22 @@
UCX already comes with two common list implementations ([linked list](linked_list.h.md) and [array list](array_list.h.md))
that should cover most use cases.
-But if you feel the need to implement an own list, you will find instructions [below](#implementing-own-list-structures).
+But if you feel the need to implement an own list, you will find instructions [below](#implement-own-list-structures).
+
+## Example
-## Overview
+
+TODO: add example how to work with lists
+
+
+> If you want to lazy-initialize lists, you can use the global `cxEmptyList` symbol as a placeholder instead of using a `NULL`-pointer.
+> While you *must not* insert items into that list, you can safely access this list or create iterators.
+> This allows you to write clean code without checking for `NULL`-pointer everywhere.
+> You still need to make sure that the placeholder is replaced with an actual list before inserting items.
+
+## Insert
```C
-size_t cxListSize(const CxList *list);
-
int cxListAdd(CxList *list, const void *elem);
size_t cxListAddArray(CxList *list, const void *array, size_t n);
@@ -32,7 +41,33 @@
int cxListInsertAfter(CxIterator *iter, const void *elem);
int cxListInsertBefore(CxIterator *iter, const void *elem);
+```
+
+TODO: add documentation
+
+
+## Access and Find
+
+```C
+size_t cxListSize(const CxList *list);
+
+void *cxListAt(const CxList *list, size_t index);
+
+size_t cxListFind(const CxList *list, const void *elem);
+
+size_t cxListFindRemove(CxList *list, const void *elem);
+
+bool cxListIndexValid(const CxList *list, size_t index);
+```
+
+
+TODO: add documentation
+
+
+## Remove
+
+```C
int cxListRemove(CxList *list, size_t index);
int cxListRemoveAndGet(CxList *list, size_t index, void *targetbuf);
@@ -43,19 +78,15 @@
void *targetbuf);
void cxListClear(CxList *list);
-
-int cxListSwap(CxList *list, size_t i, size_t j);
-
-void *cxListAt(const CxList *list, size_t index);
-
-CxIterator cxListIteratorAt(const CxList *list, size_t index);
+```
-CxIterator cxListBackwardsIteratorAt(const CxList *list, size_t index);
+
+TODO: add documentation
+
-CxIterator cxListMutIteratorAt(CxList *list, size_t index);
+## Iterators
-CxIterator cxListMutBackwardsIteratorAt(CxList *list, size_t index);
-
+```C
CxIterator cxListIterator(const CxList *list);
CxIterator cxListMutIterator(CxList *list);
@@ -64,25 +95,58 @@
CxIterator cxListMutBackwardsIterator(CxList *list);
-size_t cxListFind(const CxList *list, const void *elem);
+CxIterator cxListIteratorAt(const CxList *list, size_t index);
+
+CxIterator cxListBackwardsIteratorAt(const CxList *list, size_t index);
+
+CxIterator cxListMutIteratorAt(CxList *list, size_t index);
+
+CxIterator cxListMutBackwardsIteratorAt(CxList *list, size_t index);
+```
-bool cxListIndexValid(const CxList *list, size_t index);
+
+TODO: add documentation
+
-size_t cxListFindRemove(CxList *list, const void *elem);
+## Reorder
+
+```C
+int cxListSwap(CxList *list, size_t i, size_t j);
void cxListSort(CxList *list);
void cxListReverse(CxList *list);
-
-int cxListCompare(const CxList *list, const CxList *other);
+```
-void cxListFree(CxList *list);
+
+TODO: add documentation
+
-extern CxList *const cxEmptyList;
+## Compare
+
+```C
+int cxListCompare(const CxList *list, const CxList *other);
```
+
+TODO: add documentation
+
-## Implementing own List Structures
+## Dispose
+
+```C
+void cxListFree(CxList *list);
+```
+
+
+TODO: add documentation
+
+
+## Implement own List Structures
+
+
+TODO: add documentation
+