Populate the docs

README.md

@@ -1,3 +1,13 @@
 # Cavl
 
-Generic C implementation of AVL tree suitable for deeply embedded systems distributed in a single header file.
+[![Main Workflow](https://github.com/pavel-kirienko/cavl/actions/workflows/main.yml/badge.svg)](https://github.com/pavel-kirienko/cavl/actions/workflows/main.yml)
+
+Generic single-header implementation of AVL tree in C99 suitable for deeply embedded systems.
+**Simply copy `cavl.h` into your project tree and you are ready to roll.**
+The usage instructions are provided in the comments.
+
+A complete test suite is provided in `test.cpp`; it includes an exhaustive randomized test.
+
+For development-related instructions please refer to the CI configuration file.
+
+![Tree](randomized_test_tree.png "Random tree generated by the test suite")

cavl.h

@@ -51,20 +51,20 @@ struct Cavl
 static_assert(sizeof(Cavl) <= sizeof(void* [4]));
 #endif
 
-/// Returns positive if the search target is greater than the provided node, negative if smaller, zero on match (found).
+/// Returns POSITIVE if the search target is GREATER than the provided node, negative if smaller, zero on match (found).
 /// Values other than {-1, 0, +1} are not recommended to avoid overflow during the narrowing conversion of the result.
 typedef int8_t (*CavlPredicate)(void* user_reference, const Cavl* node);
 
-/// If provided, the factory is invoked if the sought node could not be found.
-/// It is expected to return a new node that will be inserted immediately without the need to traverse the tree again.
+/// If provided, the factory will be invoked when the sought node does not exist in the tree.
+/// It is expected to return a new node that will be inserted immediately (without the need to traverse the tree again).
 /// If the factory returns NULL or is not provided, the tree is not modified.
 typedef Cavl* (*CavlFactory)(void* user_reference);
 
 /// Look for a node in the tree using the specified search predicate. The worst-case complexity is O(log n).
 /// - If the node is found, return it.
 /// - If the node is not found and the factory is NULL, return NULL.
 /// - Otherwise, construct a new node using the factory; if the result is not NULL, insert it; return the result.
-/// The user_reference is passed into the predicate/factory unmodified.
+/// The user_reference is passed into the predicate & factory unmodified.
 /// The root node may be replaced in the process.
 /// If predicate is NULL, returns NULL.
 static inline Cavl* cavlSearch(Cavl** const root,