[btr]: Minor documentation improvements.

diff --git a/buffer_tree.c b/buffer_tree.c
index bbd055b970c09d22beb13b03d446294752426d71..9a59fff9c0419ac95ea4f71c62ef87e108973dbb 100644 (file)
--- a/buffer_tree.c
+++ b/buffer_tree.c
@@ -36,7 +36,7 @@ struct btr_node {
        struct list_head input_queue;
 };
 
-#define FOR_EACH_TARGET_NODE(_tn, _btrn) list_for_each_entry((_tn), \
+#define FOR_EACH_CHILD(_tn, _btrn) list_for_each_entry((_tn), \
        &((_btrn)->children), node)
 
 #define FOR_EACH_BUFFER_REF(_br, _btrn) \
@@ -59,6 +59,11 @@ struct btr_node *btr_new_node(char *name, struct btr_node *parent)
        return btrn;
 }
 
+/*
+ * Allocate a new btr buffer.
+ *
+ * The freshly allocated buffer will have a zero refcount.
+ */
 static struct btr_buffer *new_btrb(char *buf, size_t size)
 {
        struct btr_buffer *btrb = para_malloc(sizeof(*btrb));
@@ -69,6 +74,9 @@ static struct btr_buffer *new_btrb(char *buf, size_t size)
        return btrb;
 }
 
+/*
+ * Deallocate the reference, release the resources if refcount drops to zero.
+ */
 void btr_drop_buffer_reference(struct btr_buffer_reference *br)
 {
        struct btr_buffer *btrb = br->btrb;
@@ -82,15 +90,15 @@ void btr_drop_buffer_reference(struct btr_buffer_reference *br)
        }
 }
 
-static void add_btrb_to_targets(struct btr_buffer *btrb, struct btr_node *btrn)
+static void add_btrb_to_children(struct btr_buffer *btrb, struct btr_node *btrn)
 {
-       struct btr_node *tn; /* target node */
+       struct btr_node *ch;
 
-       FOR_EACH_TARGET_NODE(tn, btrn) {
+       FOR_EACH_CHILD(ch, btrn) {
                struct btr_buffer_reference *br = para_malloc(sizeof(*br));
                br->btrb = btrb;
                br->consumed = 0;
-               list_add_tail(&br->node, &tn->input_queue);
+               list_add_tail(&br->node, &ch->input_queue);
                btrb->refcount++;
        }
 }
@@ -100,12 +108,12 @@ void btr_add_output(char *buf, size_t size, struct btr_node *btrn)
        struct btr_buffer *btrb;
 
        btrb = new_btrb(buf, size);
-       add_btrb_to_targets(btrb, btrn);
+       add_btrb_to_children(btrb, btrn);
 }
 
 void btr_pushdown_br(struct btr_buffer_reference *br, struct btr_node *btrn)
 {
-       add_btrb_to_targets(br->btrb, btrn);
+       add_btrb_to_children(br->btrb, btrn);
        btr_drop_buffer_reference(br);
 }
 
@@ -117,7 +125,8 @@ void btr_pushdown(struct btr_node *btrn)
                btr_pushdown_br(br, btrn);
 }
 
-bool btr_no_children(struct btr_node *btrn)
+/* Return true if this node has no children. */
+bool btr_is_leaf_node(struct btr_node *btrn)
 {
        return list_empty(&btrn->children);
 }
@@ -168,10 +177,10 @@ static void flush_input_queue(struct btr_node *btrn)
 
 void btr_del_node(struct btr_node *btrn)
 {
-       struct btr_node *tn;
+       struct btr_node *ch;
 
-       FOR_EACH_TARGET_NODE(tn, btrn)
-               tn->parent = NULL;
+       FOR_EACH_CHILD(ch, btrn)
+               ch->parent = NULL;
        flush_input_queue(btrn);
        if (btrn->parent)
                list_del(&btrn->node);