# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1743935920 -7200
# Node ID 0f21abc5224156f2aca56c115b515b8e54a0af7c
# Parent  03e9360e98f59a7725c2956d2130f0f355e9551b
complete tree documentation

relates to #451

diff -r 03e9360e98f5 -r 0f21abc52241 docs/Writerside/topics/tree.h.md
--- a/docs/Writerside/topics/tree.h.md	Sat Apr 05 14:18:37 2025 +0200
+++ b/docs/Writerside/topics/tree.h.md	Sun Apr 06 12:38:40 2025 +0200
@@ -190,14 +190,39 @@
         ptrdiff_t loc_parent,
         ptrdiff_t loc_children, ptrdiff_t loc_last_child,
         ptrdiff_t loc_prev, ptrdiff_t loc_next);
+```
 
+The low-level function `cx_tree_link()` adds a `node` to a new `parent`, unlinking it from its previous parent, if required.
+
+The functions `cx_tree_add_array()` and `cx_tree_add_iter()` are equivalent,
+except that the former adds `n` items of size `elem_size` from the `src` array,
+and the latter adds _up to_ `n` items from the iterator `iter`.
+For each element, the `cfun` is called with the element as first argument and the `cdata` context as second argument.
+The `cfun` function is supposed to return a node for which then the `sfunc` is used to find the location where to insert the node.
+If a node could not be added, because `sfunc` always returns a negative number, it is stored at the location where `failed` points to.
+
+> The functions `cx_tree_add_array()` and `cx_tree_add_iter()` are optimized for adding multiple nodes to
+> the same subtree without starting the search all over from the root node.
+> This behavior can be controlled with `cx_tree_add_look_around_depth`, which specifies for how many parent nodes
+> the algorithm backtracks in the current subtree before restarting the search from the root node.
+
+The function `cx_tree_add()` is similar to the other add-functions,
+except that it does only add one single item to the tree and always stores the created node at the location where `cnode` points to.
+
+> By design, the add-functions can only be used to add children to the tree.
+> If you want to add a new root node, this is much easier by simply calling `cx_tree_link(newroot, oldroot, layout...)` .
+
+The following high-level functions can be used to add nodes to a `CxTree`.
+
+```C
+#include <cx/tree.h>
 
 int cxTreeAddChild(CxTree *tree, void *parent, const void *data);
 
 void cxTreeAddChildNode(CxTree *tree, void *parent, void *child);
 
 void cxTreeSetParent(CxTree *tree, void *parent, void *child);
-        
+
 int cxTreeInsert(CxTree *tree, const void *data);
 
 size_t cxTreeInsertIter(CxTree *tree, CxIteratorBase *iter, size_t n);
@@ -206,9 +231,22 @@
         size_t elem_size, size_t n);
 ```
 
-<warning>
-TODO: document
-</warning>
+The functions `cxTreeAddChild()`, `cxTreeAddChildNode()`, and `cxTreeSetParent()` are similar to `cx_tree_link()`.
+The difference between `cxTreeAddChild()` and `cxTreeAddChildNode()` is,
+that `cxTreeAddChild()` uses the `cx_tree_node_create_func` of the `CxTree` to create the node first, before adding it.
+The function returns non-zero in case the creation of the node fails.
+The difference between `cxTreeSetParent()` and `cxTreeAddChildNode()` is,
+that `cxTreeSetParent()` does not increase the tree size, when `child` already had a parent.
+
+> Use `cxTreeAddChildNode()` to add _new_ nodes to the tree and `cxTreeSetParent()`
+> to relink a subtree of the `tree` with a new parent.
+> 
+> Using `cxTreeSetParent()` on a `child` which already has a parent in a _different_ tree is a mistake.
+
+The functions `cxTreeInsert()`, `cxTreeInsertIter()`, and `cxTreeInsertArray()` behave
+like `cx_tree_add()`, `cx_tree_add_iter()`, and `cx_tree_add_array()`.
+As creation context `cdata` for the `cx_tree_node_create_func` a pointer to the `CxTree` is passed.
+Instead of returning a `failed` node, like the low-level functions, the high-level functions automatically free the memory for the failed node.
 
 ## Size and Depth