[2106] updated documentation

src/lib/datasrc/rbtree.h

@@ -1015,10 +1015,26 @@ public:
     /// \brief Find with callback and node chain
     /// \anchor callback
     ///
+    /// This version of \c find() is specifically designed for the backend
+    /// of the \c InMemoryZoneFinder class, and implements all necessary
+    /// features for that purpose.  Other applications shouldn't need these
+    /// additional features, and should normally use the simpler versions.
+    ///
     /// This version of \c find() calls the callback whenever traversing (on
     /// the way from root down the tree) a marked node on the way down through
     /// the domain namespace (see \c RBNode::FLAG_CALLBACK).
     ///
+    /// Also, this version takes a \c LabelSequence object, not a \c Name
+    /// object to be as efficient as possible; operations on the former
+    /// needed for the search are generally much more efficient than those
+    /// for the latter.  Since \c Name objects are more commonly used
+    /// in other parts of the implementation, other versions take a \c Name
+    /// and convert it to \c LabelSequence.  This conversion is cheap,
+    /// while the other direction isn't, and since there would be cases
+    /// where an implementation primarily handles \c LabelSequence objects
+    /// as an efficient representation of names, it would make most sense
+    /// to provide the interface that takes \c LabelSequence.
+    ///
     /// If you return true from the callback, the search is stopped and a
     /// PARTIALMATCH is returned with the given node. Note that this node
     /// doesn't really need to be the one with longest possible match.
@@ -1049,17 +1065,14 @@ public:
     ///
     /// This feature can be used to get the absolute name for a node;
     /// to do so, we need to travel upside from the node toward the root,
-    /// concatenating all ancestor names.  With the current implementation
-    /// it's not possible without a node chain, because there is a no pointer
-    /// from the root of a subtree to the parent subtree (this may change
-    /// in a future version).  A node chain can also be used to find the
-    /// next and previous nodes of a given node in the entire RBTree;
+    /// concatenating all ancestor labels.  A node chain can also be used to
+    /// find the next and previous nodes of a given node in the entire RBTree;
     /// the \c nextNode() and \c previousNode() methods take a node
     /// chain as a parameter.
     ///
     /// \exception isc::BadValue node_path is not empty.
     ///
-    /// \param target_labels Target to be found
+    /// \param target_labels_orig Target to be found
     /// \param node On success (either \c EXACTMATCH or \c PARTIALMATCH)
     ///     it will store a pointer to the matching node
     /// \param node_path Other search details will be stored (see the
@@ -1072,7 +1085,7 @@ public:
     /// \return As in the description, but in case of callback returning
     ///     \c true, it returns immediately with the current node.
     template <typename CBARG>
-    Result find(const isc::dns::LabelSequence& target_labels,
+    Result find(const isc::dns::LabelSequence& target_labels_orig,
                 RBNode<T>** node,
                 RBTreeNodeChain<T>& node_path,
                 bool (*callback)(const RBNode<T>&, CBARG),

src/lib/datasrc/tests/rbtree_unittest.cc

@@ -283,10 +283,11 @@ testCallback(const RBNode<int>&, bool* callback_checker) {
 
 template <typename T>
 void
-performCallbackTest(RBTree<int> &rbtree,
+performCallbackTest(RBTree<int>& rbtree,
                     util::MemorySegmentLocal& mem_sgmt,
                     const T& name_called,
-                    const T& name_not_called) {
+                    const T& name_not_called)
+{
     RBNode<int>* rbtnode;
     const RBNode<int>* crbtnode;