Mercurial > hg > ucx / file diff

--- a/src/cx/tree.h	Mon Aug 19 20:46:36 2024 +0200
+++ b/src/cx/tree.h	Tue Aug 20 11:02:54 2024 +0200
@@ -549,7 +549,14 @@
  * in case \p sfunc returned a direct match, the already found node.
  *
  * If \p cfunc returns a new node pointer, it will be linked into the tree.
- * Otherwise, this function just returns the found node.
+ * When \p sfunc returned a positive integer, the new node will be linked as a
+ * child. When \p sfunc returned zero and the found node has a parent, the new
+ * node will be added as sibling - otherwise, the new node will be the new root.
+ * When \p sfunc returned a negative value, the new node will always be the
+ * new root.
+ *
+ * If \p cfunc returns an existing node found by \p sfunc, this function just
+ * returns the found node without modifying the tree.
  *
  * This function may return \c NULL when \p cfunc tries to allocate a new node
  * but fails to do so.
@@ -557,8 +564,7 @@
  * The \p root argument shall point to a location where the pointer to the root
  * node is stored. The pointer to the root node may be \c NULL in which case
  * this function will instantly create a new node and write the location to
- * \p root. On the other hand, if \p sfunc returns a negative integer for
- * \c *root, the newly created node will be the new root node.
+ * \p root.
  *
  * Multiple elements can be added more efficiently with
  * #cx_tree_add_array() or #cx_tree_add_iter().