Documentation step 5: Properly document navigation and jumping functions.

diff --git a/xml-tree.hpp b/xml-tree.hpp
index 4ada586..fd396e7 100644 (file)
--- a/xml-tree.hpp
+++ b/xml-tree.hpp
@@ -187,25 +187,158 @@ public:
   tag_t register_tag(char *s);
 
   //Navigation functions
+
+  /**
+   * [root()] returns the root node of the tree.
+   * Runs in O(1)
+   */
   inline node_t root () const;
+
+  /**
+   * [child(n, i)] returns the [i]th child of [n]
+   * Runs in O(i) (?)
+   */
   node_t child(node_t, uint32_t) const;
+
+  /**
+   * [parent(n)] returns the parent node of [n]. Returns
+   * xml_tree::NIL if [n] is the root of the tree.
+   * Runs in O(1)
+   */
   inline node_t parent(node_t) const;
+
+  /**
+   * [first_child(n)] returns the first child of [n]. Returns
+   * xml_tree::NIL if [n] is a leaf.
+   * Runs in O(1)
+   */
   inline node_t first_child(node_t) const;
+
+  /**
+   * [last_child(n)] returns the last child of [n]. Returns
+   * xml_tree::NIL if [n] is a leaf.
+   * Runs in O(1)
+   */
   inline node_t last_child(node_t) const;
+
+  /**
+   * [next_sibling(n)] returns the following sibling of  [n].
+   * Returns xml_tree::NIL if [n] is the last of its siblings.
+   * Runs in O(1)
+   */
   inline node_t next_sibling(node_t) const;
+
+  /**
+   * [prev_sibling(n)] returns the preceding sibling of  [n].
+   * Returns xml_tree::NIL if [n] is the first of its siblings.
+   * Runs in O(1)
+   */
   inline node_t prev_sibling(node_t) const;
+
+  /**
+   * [first_element(n)] returns the first child of [n] which
+   * corresponds to an element node. Returns xml_tree::NIL if
+   * no such node exists.
+   * Runs in O(1)
+   */
   inline node_t first_element(node_t) const;
+
+  /**
+   * [next_element(n)] returns the first following sibling of [n] which
+   * corresponds to an element node. Returns xml_tree::NIL if
+   * no such node exists.
+   * Runs in O(1)
+   */
   inline node_t next_element(node_t) const;
-  inline node_t tagged_next_close(node_t, tag_t) const;
+
+  /**
+   * [tagged_next(n, t)] returns the first node following [n] in pre-order
+   * which has tag [t].  Returns xml_tree::NIL if no such node exists.
+   * Runs in O(1)
+   */
   inline node_t tagged_next(node_t, tag_t) const;
+
+  /**
+   * [tagged_next_close(n, t)], like [tagged_next(n, t)] but uses a euristic to
+   * return the result faster if the next tag is close to [n].
+   * Runs in O(1)
+   */
+  inline node_t tagged_next_close(node_t, tag_t) const;
+
+  /**
+   * [tagged_descendant(n, t)] returns the first descendant of [n] in
+   * pre-order which has tag [t].  Returns xml_tree::NIL if no such node
+   * exists.
+   * Runs in O(1)
+   */
   inline node_t tagged_descendant(node_t, tag_t) const;
+
+  /**
+   * [tagged_following_before(n, t, m)] returns the first following node
+   * of [n] in pre-order which has tag [t] and which occurs before node
+   * [m]. Returns xml_tree::NIL if no such node exists.
+   * Runs in O(1)
+   */
   inline node_t tagged_following_before(node_t, tag_t, node_t) const;
+
+  /**
+   * [tagged_child(n, t)] returns the first child of [n] in
+   * pre-order which has tag [t].  Returns xml_tree::NIL if no such node
+   * exists.
+   * Runs in O(1)
+   */
   inline node_t tagged_child(node_t, tag_t) const;
+
+  /**
+   * [tagged_sibling(n, t)] returns the first following sibling of [n] in
+   * pre-order which has tag [t].  Returns xml_tree::NIL if no such node
+   * exists.
+   * Runs in O(1)
+   */
   inline node_t tagged_sibling(node_t, tag_t) const;
+
+  /**
+   * [select_child(n, tags)] returns the first child of [n] in
+   * pre-order which has a tag in [tags]. [tags] is a xml_tree::NIL_TAG_ID
+   * terminated array of xml_tree::tag_t. Returns xml_tree::NIL if no such
+   * node exists.
+   * Runs in O(sizeof(tags))
+   */
   node_t select_child(node_t, tag_t*) const;
+
+  /**
+   * [select_descendant(n, tags)] returns the first descendant of [n] in
+   * pre-order which has a tag in [tags]. [tags] is a xml_tree::NIL_TAG_ID
+   * terminated array of xml_tree::tag_t. Returns xml_tree::NIL if no such
+   * node exists.
+   * Runs in O(sizeof(tags))
+   */
   inline node_t select_descendant(node_t, tag_t*) const;
+
+  /**
+   * [select_sibling(n, tags)] returns the first following sibling of
+   * of [n] in pre-order which has a tag in [tags].
+   * [tags] is a xml_tree::NIL_TAG_ID terminated array of xml_tree::tag_t.
+   * Returns xml_tree::NIL if no such node exists.
+   * Runs in O(sizeof(tags))
+   */
   node_t select_sibling(node_t, tag_t*) const;
+
+  /**
+   * [select_sibling(n, tags, m)] returns the first following node
+   * of [n] in pre-order which has a tag in [tags] and which occurs before
+   * node [m]. [tags] is a xml_tree::NIL_TAG_ID terminated array of
+   * xml_tree::tag_t. Returns xml_tree::NIL if no such node exists.
+   * Runs in O(sizeof(tags))
+   */
   inline node_t select_following_before (node_t, tag_t*, node_t) const;
+
+  /**
+   * [closing(n)] returns the node identifier corresponding to the closing
+   * parenthesis associated with [n] in the underlying BP representation.
+   * The result is undefined if [n] does not point to an opening parenthesis.
+   * Runs in O(1).
+   */
   inline node_t closing(node_t) const;
 
   //Text functions