--- a/src/cx/tree.h Sat Oct 11 15:42:48 2025 +0200
+++ b/src/cx/tree.h Sun Oct 12 20:21:56 2025 +0200
@@ -49,12 +49,12 @@
*
* This iterator is not position-aware in a strict sense, as it does not assume
* a particular order of elements in the tree. However, the iterator keeps track
- * of the number of nodes it has passed in a counter variable.
+ * of the number of nodes it has passed in a counter-variable.
* Each node, regardless of the number of passes, is counted only once.
*
* @note Objects that are pointed to by an iterator are mutable through that
* iterator. However, if the
- * underlying data structure is mutated by other means than this iterator (e.g.
+ * underlying data structure is mutated by other means than this iterator (e.g.,
* elements added or removed), the iterator becomes invalid (regardless of what
* cxIteratorValid() returns).
*
@@ -71,7 +71,7 @@
bool skip;
/**
* Set to true, when the iterator shall visit a node again
- * when all it's children have been processed.
+ * when all its children have been processed.
*/
bool visit_on_exit;
/**
@@ -97,7 +97,7 @@
*/
void *node;
/**
- * Stores a copy of the next pointer of the visited node.
+ * Stores a copy of the pointer to the successor of the visited node.
* Allows freeing a node on exit without corrupting the iteration.
*/
void *node_next;
@@ -155,12 +155,12 @@
*
* This iterator is not position-aware in a strict sense, as it does not assume
* a particular order of elements in the tree. However, the iterator keeps track
- * of the number of nodes it has passed in a counter variable.
+ * of the number of nodes it has passed in a counter-variable.
* Each node, regardless of the number of passes, is counted only once.
*
* @note Objects that are pointed to by an iterator are mutable through that
* iterator. However, if the
- * underlying data structure is mutated by other means than this iterator (e.g.
+ * underlying data structure is mutated by other means than this iterator (e.g.,
* elements added or removed), the iterator becomes invalid (regardless of what
* cxIteratorValid() returns).
*
@@ -250,7 +250,7 @@
/**
* Links a node to a (new) parent.
*
- * If the node has already a parent, it is unlinked, first.
+ * If the node already has a parent, it is unlinked, first.
* If the parent has children already, the node is @em appended to the list
* of all currently existing children.
*
@@ -318,8 +318,8 @@
* Zero means exact match and a positive number is an implementation defined
* measure for the distance to an exact match.
*
- * For example if a tree stores file path information, a node that is
- * describing a parent directory of a filename that is searched, shall
+ * For example, consider a tree that stores file path information.
+ * A node which is describing a parent directory of a searched file shall
* return a positive number to indicate that a child node might contain the
* searched item. On the other hand, if the node denotes a path that is not a
* prefix of the searched filename, the function would return -1 to indicate
@@ -330,7 +330,7 @@
*
* @return 0 if the node contains the data,
* positive if one of the children might contain the data,
- * negative if neither the node, nor the children contains the data
+ * negative if neither the node nor the children contains the data
*/
cx_attr_nonnull
typedef int (*cx_tree_search_data_func)(const void *node, const void *data);
@@ -348,8 +348,8 @@
* Zero means exact match and a positive number is an implementation defined
* measure for the distance to an exact match.
*
- * For example if a tree stores file path information, a node that is
- * describing a parent directory of a filename that is searched, shall
+ * For example, consider a tree that stores file path information.
+ * A node which is describing a parent directory of a searched file shall
* return a positive number to indicate that a child node might contain the
* searched item. On the other hand, if the node denotes a path that is not a
* prefix of the searched filename, the function would return -1 to indicate
@@ -360,7 +360,7 @@
*
* @return 0 if @p node contains the same data as @p new_node,
* positive if one of the children might contain the data,
- * negative if neither the node, nor the children contains the data
+ * negative if neither the node nor the children contains the data
*/
cx_attr_nonnull
typedef int (*cx_tree_search_func)(const void *node, const void *new_node);
@@ -368,11 +368,11 @@
/**
* Searches for data in a tree.
*
- * When the data cannot be found exactly, the search function might return a
- * closest result which might be a good starting point for adding a new node
+ * When the data cannot be found exactly, the search function might return the
+ * closest result, which might be a good starting point for adding a new node
* to the tree (see also #cx_tree_add()).
*
- * Depending on the tree structure it is not necessarily guaranteed that the
+ * Depending on the tree structure, it is not necessarily guaranteed that the
* "closest" match is uniquely defined. This function will search for a node
* with the best match according to the @p sfunc (meaning: the return value of
* @p sfunc which is closest to zero). If that is also ambiguous, an arbitrary
@@ -406,10 +406,10 @@
* Searches for a node in a tree.
*
* When no node with the same data can be found, the search function might
- * return a closest result which might be a good starting point for adding the
+ * return the closest result, which might be a good starting point for adding the
* new node to the tree (see also #cx_tree_add()).
*
- * Depending on the tree structure it is not necessarily guaranteed that the
+ * Depending on the tree structure, it is not necessarily guaranteed that the
* "closest" match is uniquely defined. This function will search for a node
* with the best match according to the @p sfunc (meaning: the return value of
* @p sfunc which is closest to zero). If that is also ambiguous, an arbitrary
@@ -496,8 +496,8 @@
/**
* Describes a function that creates a tree node from the specified data.
- * The first argument points to the data the node shall contain and
- * the second argument may be used for additional data (e.g. an allocator).
+ * The first argument points to the data the node shall contain, and
+ * the second argument may be used for additional data (e.g., an allocator).
* Functions of this type shall either return a new pointer to a newly
* created node or @c NULL when allocation fails.
*
@@ -637,17 +637,17 @@
* When a location is found, the @p cfunc will be invoked with @p cdata.
*
* The node returned by @p cfunc will be linked into the tree.
- * When @p sfunc returned a positive integer, the new node will be linked as a
+ * When @p sfunc returns a positive integer, the new node will be linked as a
* child. The other children (now siblings of the new node) are then checked
* with @p sfunc, whether they could be children of the new node and re-linked
* accordingly.
*
- * 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 added
+ * When @p sfunc returns zero and the found node has a parent, the new
+ * node will be added as a sibling - otherwise, the new node will be added
* as a child.
*
- * When @p sfunc returned a negative value, the new node will not be added to
- * the tree and this function returns a non-zero value.
+ * When @p sfunc returns a negative value, the new node will not be added to
+ * the tree, and this function returns a non-zero value.
* The caller should check if @p cnode contains a node pointer and deal with the
* node that could not be added.
*
@@ -747,9 +747,9 @@
* A function to create new nodes.
*
* Invocations to this function will receive a pointer to this tree
- * structure as second argument.
+ * structure as the second argument.
*
- * Nodes MAY use #cx_tree_node_base_s as base layout, but do not need to.
+ * Nodes MAY use #cx_tree_node_base_s as the base layout, but do not need to.
*/
cx_tree_node_create_func node_create;
@@ -814,7 +814,7 @@
* Macro to roll out the #cx_tree_node_base_s structure with a custom
* node type.
*
- * Must be used as first member in your custom tree struct.
+ * Must be used as the first member in your custom tree struct.
*
* @param type the data type for the nodes
*/
@@ -858,7 +858,7 @@
/**
* Member function for inserting multiple elements.
*
- * Implementations SHALL avoid to perform a full search in the tree for
+ * Implementations SHALL avoid performing a full search in the tree for
* every element even though the source data MAY be unsorted.
*/
size_t (*insert_many)(
@@ -885,7 +885,7 @@
/**
- * Destroys a node and it's subtree.
+ * Destroys a node and its subtree.
*
* It is guaranteed that the simple destructor is invoked before
* the advanced destructor, starting with the leaf nodes of the subtree.
@@ -921,7 +921,7 @@
*
* @attention Be careful when calling this function when no destructor function
* is registered that actually frees the memory of nodes. In that case you will
- * need a reference to the (former) root node of the tree somewhere or
+ * need a reference to the (former) root node of the tree somewhere, or
* otherwise you will be leaking memory.
*
* @param tree the tree
@@ -992,9 +992,9 @@
/**
* Creates a new tree structure based on a default layout.
*
- * Nodes created by @p create_func MUST contain #cx_tree_node_base_s as first
+ * Nodes created by @p create_func MUST contain #cx_tree_node_base_s as the first
* member (or at least respect the default offsets specified in the tree
- * struct) and they MUST be allocated with the specified allocator.
+ * struct), and they MUST be allocated with the specified allocator.
*
* @note This function will also register an advanced destructor which
* will free the nodes with the allocator's free() method.
@@ -1019,7 +1019,7 @@
* @attention This function will create an incompletely defined tree structure
* where neither the create function, the search function, nor a destructor
* will be set. If you wish to use any of this functionality for the wrapped
- * tree, you need to specify those functions afterwards.
+ * tree, you need to specify those functions afterward.
*
* @param allocator the allocator that was used for nodes of the wrapped tree
* (if @c NULL, the cxDefaultAllocator is assumed)
@@ -1289,7 +1289,7 @@
/**
* Sets the (new) parent of the specified child.
*
- * If the @p child is not already member of the tree, this function behaves
+ * If the @p child is not already a member of the tree, this function behaves
* as #cxTreeAddChildNode().
*
* @param tree the tree
@@ -1308,11 +1308,11 @@
/**
* Adds a new node to the tree.
*
- * If the @p child is already member of the tree, the behavior is undefined.
+ * If the @p child is already a member of the tree, the behavior is undefined.
* Use #cxTreeSetParent() if you want to move a subtree to another location.
*
* @attention The node may be externally created, but MUST obey the same rules
- * as if it was created by the tree itself with #cxTreeAddChild() (e.g. use
+ * as if it was created by the tree itself with #cxTreeAddChild() (e.g., use
* the same allocator).
*
* @param tree the tree
@@ -1336,7 +1336,7 @@
* leaving this task to the tree by using #cxTreeInsert().
*
* Be aware that adding nodes at arbitrary locations in the tree might cause
- * wrong or undesired results when subsequently invoking #cxTreeInsert() and
+ * wrong or undesired results when subsequently invoking #cxTreeInsert(), and
* the invariant imposed by the search function does not hold any longer.
*
* @param tree the tree
@@ -1395,7 +1395,7 @@
);
/**
- * Removes a node and it's subtree from the tree.
+ * Removes a node and its subtree from the tree.
*
* If the node is not part of the tree, the behavior is undefined.
*