Merge pull request #375 from kaesluder/trav-desc-doc

Expand traverse and descendants documentation: Issue #369

Author: kivikakk

src/arena_tree.rs

@@ -136,23 +136,36 @@ impl<'a, T> Node<'a, T> {
         ReverseChildren(self.last_child.get())
     }
 
-    /// Return an iterator of references to this node and its descendants, in tree order.
+    /// Return an iterator of references to this `Node` and its descendants, in tree order.
     ///
     /// Parent nodes appear before the descendants.
     /// Call `.next().unwrap()` once on the iterator to skip the node itself.
+    ///
+    /// *Similar Functions:* Use `traverse()` or `reverse_traverse` if you need
+    /// references to the `NodeEdge` structs associated with each `Node`
     pub fn descendants(&'a self) -> Descendants<'a, T> {
         Descendants(self.traverse())
     }
 
-    /// Return an iterator of references to this node and its descendants, in tree order.
+    /// Return an iterator of references to `NodeEdge` enums for each `Node` and its descendants,
+    /// in tree order.
+    ///
+    /// `NodeEdge` enums represent the `Start` or `End` of each node.
+    ///
+    /// *Similar Functions:* Use `descendants()` if you don't need `Start` and `End`.
     pub fn traverse(&'a self) -> Traverse<'a, T> {
         Traverse {
             root: self,
             next: Some(NodeEdge::Start(self)),
         }
     }
 
-    /// Return an iterator of references to this node and its descendants, in tree order.
+    /// Return an iterator of references to `NodeEdge` enums for each `Node` and its descendants,
+    /// in *reverse* order.
+    ///
+    /// `NodeEdge` enums represent the `Start` or `End` of each node.
+    ///
+    /// *Similar Functions:* Use `descendants()` if you don't need `Start` and `End`.
     pub fn reverse_traverse(&'a self) -> ReverseTraverse<'a, T> {
         ReverseTraverse {
             root: self,