tinkerpop git commit: Clarification around random walks CTR

[sp...@apache.org]

Repository: tinkerpop
Updated Branches:
  refs/heads/tp32 7c7dddb72 -> aef2f6ca0


Clarification around random walks CTR


Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/aef2f6ca
Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/aef2f6ca
Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/aef2f6ca

Branch: refs/heads/tp32
Commit: aef2f6ca0f8f1f62cb8220b01afc49d70714692f
Parents: 7c7dddb
Author: Stephen Mallette <sp...@genoprime.com>
Authored: Fri Jun 22 08:31:16 2018 -0400
Committer: Stephen Mallette <sp...@genoprime.com>
Committed: Fri Jun 22 08:31:16 2018 -0400

----------------------------------------------------------------------
 docs/src/reference/the-traversal.asciidoc | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/aef2f6ca/docs/src/reference/the-traversal.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/reference/the-traversal.asciidoc b/docs/src/reference/the-traversal.asciidoc
index b600b7a..8cc6ac0 100644
--- a/docs/src/reference/the-traversal.asciidoc
+++ b/docs/src/reference/the-traversal.asciidoc
@@ -2191,6 +2191,25 @@ g.V(1).repeat(local(
        )).times(10).path()
 ----
 
+As a clarification, note that in the above example `local()` is not strictly required as it only does the random walk
+over a single vertex, but note what happens without it if multiple vertices are traversed:
+
+[gremlin-groovy,modern]
+----
+g.V().repeat(bothE().sample(1).by('weight').otherV()).times(5).path()
+----
+
+The use of `local()` ensures that the traversal over `bothE()` occurs once per vertex traverser that passes through,
+thus allowing one random walk per vertex.
+
+[gremlin-groovy,modern]
+----
+g.V().repeat(local(bothE().sample(1).by('weight').otherV())).times(5).path()
+----
+
+So, while not strictly required, it is likely better to be explicit with the use of `local()` so that the proper intent
+of the traversal is expressed.
+
 *Additional References*
 
 link:++http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#sample-int-++[`sample(int)`],