Mercurial > hg > ucx / changeset

--- a/docs/Writerside/topics/tree.h.md	Wed Apr 02 20:25:50 2025 +0200
+++ b/docs/Writerside/topics/tree.h.md	Thu Apr 03 23:59:31 2025 +0200
@@ -296,9 +296,19 @@
 void cxTreeVisitorDispose(CxTreeVisitor *visitor);
 ```
 
-<warning>
-TODO: document
-</warning>
+There are two different kind of iterators for trees.
+The `CxTreeIterator` is performing a depth-first iteration with the capability of visiting a node twice:
+first when the iterator enters the node coming from its parent, and secondly when the iterator tracks back from its last child.
+On the other hand, the `CxTreeVisitor` performs a breadth-first iteration and visits every node only once.
+
+Since tree iteration needs to keep track of a stack (depth-first) or queue (breadth-frist), internal memory is allocated.
+This memory is _automatically_ disposed when the iteration _completes_.
+If you break from the iteration early, you must call `cxTreeIteratorDispose()` or `cxTreeVisitorDispose()`, respectively, to deallocate the memory.
+
+> It is strongly recommended to always invoke the dispose functions, even when it seems not necessary.
+> In the best case it just does nothing, but calling them guarantees that no memory can be leaking.
+>{style="note"}
+
 
 ## Remove