add more docs

Author: peter-toth

datafusion/common/src/tree_node.rs

@@ -127,6 +127,9 @@ pub trait TreeNode: Sized + Clone {
     /// f_up(ChildNode2)
     /// f_up(ParentNode)
     /// ```
+    ///
+    /// See [`TreeNodeRecursion`] for more details on how the traversal can be controlled.
+    ///
     /// If `f_down` or `f_up` returns [`Err`], recursion is stopped immediately.
     fn transform<FD, FU>(self, f_down: &mut FD, f_up: &mut FU) -> Result<Self>
     where
@@ -199,11 +202,27 @@ pub trait TreeNode: Sized + Clone {
     /// Implements the [visitor pattern](https://en.wikipedia.org/wiki/Visitor_pattern) for
     /// recursively transforming [`TreeNode`]s.
     ///
-    /// When passed to [`TreeNode::rewrite()`], [`TreeNodeRewriter::f_down()`] and
-    /// [`TreeNodeRewriter::f_up()`] are invoked recursively on an node tree.
+    /// E.g. for an tree such as:
+    /// ```text
+    /// ParentNode
+    ///    left: ChildNode1
+    ///    right: ChildNode2
+    /// ```
+    ///
+    /// The nodes are visited using the following order:
+    /// ```text
+    /// TreeNodeRewriter::f_down(ParentNode)
+    /// TreeNodeRewriter::f_down(ChildNode1)
+    /// TreeNodeRewriter::f_up(ChildNode1)
+    /// TreeNodeRewriter::f_down(ChildNode2)
+    /// TreeNodeRewriter::f_up(ChildNode2)
+    /// TreeNodeRewriter::f_up(ParentNode)
+    /// ```
+    ///
     /// See [`TreeNodeRecursion`] for more details on how the traversal can be controlled.
     ///
-    /// If an [`Err`] result is returned, recursion is stopped immediately.
+    /// If [`TreeNodeRewriter::f_down()`] or [`TreeNodeRewriter::f_up()`] returns [`Err`],
+    /// recursion is stopped immediately.
     fn rewrite<R: TreeNodeRewriter<Node = Self>>(self, rewriter: &mut R) -> Result<Self> {
         let (new_node, tnr) = rewriter.f_down(self)?;
         match tnr {