Merge branch '3.8-dev'

Author: spmallette

docs/src/reference/the-traversal.asciidoc

@@ -4855,6 +4855,22 @@ g.V().has('name','josh').out('created').values('name').
 <1> When the `tree()` is created, vertex 3 and 5 are unique and thus, form unique branches in the tree structure.
 <2> When the `tree()` is `by()`-modulated by `label`, then vertex 3 and 5 are both "software" and thus are merged to a single node in the tree.
 
+The `tree()` step can also take a side-effect key as an argument. When using this form, the `Tree` is constructed
+lazily, such that it becomes possible to assess its contents as each traverser passes through.
+
+[gremlin-groovy,modern]
+----
+g.V().has('name','josh').out('created').values('name').tree('x').select('x')
+----
+
+You can use `cap()` step to force `tree()` to consume the traversal stream eagerly and output results similar to prior
+examples.
+
+[gremlin-groovy,modern]
+----
+g.V().has('name','josh').out('created').values('name').tree('x').cap('x')
+----
+
 *Additional References*
 
 link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#tree()++[`tree()`],