From 22c2b86e17c4bce30de469a788542d99f5eca4f0 Mon Sep 17 00:00:00 2001
From: Blair Steven <blair.steven@alliedtelesis.co.nz>
Date: Tue, 21 Jun 2022 13:27:57 +1200
Subject: [PATCH] Add comments to cb_gather_search and apteryx_query

---
 apteryx.h   |  9 +++++++++
 callbacks.c | 13 ++++++++++++-
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/apteryx.h b/apteryx.h
index d20d344..38c0d75 100644
--- a/apteryx.h
+++ b/apteryx.h
@@ -453,6 +453,15 @@ GNode *apteryx_get_tree (const char *path);
 
 /**
  * Get a tree of multiple values from Apteryx that match this tree below the root path given.
+ *
+ * This tree may be set up with full paths to given values to be fetched, with intermediate wildcard
+ * nodes indicated by key of "*" that will match all paths that can be found at that level, leaf
+ * nodes with "*" that will match the full tree below that path, and /
+ * or with leaf nodes with empty keys "" that will match values at exactly that level.
+ *
+ * This matching is the same as apteryx_watch, provide, index and refresh when the tree
+ * is set up with apteryx_path_to_node.
+ *
  * @param root pointer to the N-ary tree of nodes.
  * @return N-ary tree of nodes.
  * Example: Create a tree and get the n-ary tree with the values for the given nodes
diff --git a/callbacks.c b/callbacks.c
index 10ac6d9..a7eec95 100644
--- a/callbacks.c
+++ b/callbacks.c
@@ -201,7 +201,16 @@ cb_release (cb_info_t *cb)
 static GList *
 cb_gather_search (struct callback_node *node, GList *callbacks_so_far, const char *path)
 {
-    /* Terminating condition */
+    /* If we are down to a directory match then the possible matches below here
+     * are:
+     *    - any nodes with more children under them
+     *    - terminal nodes with directory or exact matches
+     *
+     * Complicating things a little bit is we can get here with an empty string
+     * (usually at the start of searching a tree) - in that case we need to
+     * do the same sort of checking to traverse lower in the tree with subsequent
+     * calls.
+     */
     if (strlen (path) == 0 || strcmp (path, "/") == 0)
     {
         GList *children = hashtree_children_get (&node->hashtree_node);
@@ -232,6 +241,7 @@ cb_gather_search (struct callback_node *node, GList *callbacks_so_far, const cha
         *strchr (tmp, '/') = '\0';
     }
 
+    /* If this callback tree has a wildcard node we need to follow down that branch. */
     struct hashtree_node *next_stage = hashtree_path_to_node (&node->hashtree_node, "/*");
     if (next_stage)
     {
@@ -244,6 +254,7 @@ cb_gather_search (struct callback_node *node, GList *callbacks_so_far, const cha
     if (asprintf (&with_leading_slash, "/%s", tmp) < 0)
         return callbacks_so_far;
 
+    /* Find the next piece and move down. */
     next_stage = hashtree_path_to_node (&node->hashtree_node, with_leading_slash);
     if (next_stage)
     {