tinkerpop git commit: Added some javadoc on Scoping as taken from the mailing list

[sp...@apache.org]

Repository: tinkerpop
Updated Branches:
  refs/heads/tp32 5e4ae4669 -> ea10316e7


Added some javadoc on Scoping as taken from the mailing list


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

Branch: refs/heads/tp32
Commit: ea10316e744476b12a68a07491d0db2b028ec65c
Parents: 5e4ae46
Author: Stephen Mallette <sp...@genoprime.com>
Authored: Mon Oct 16 07:32:09 2017 -0400
Committer: Stephen Mallette <sp...@genoprime.com>
Committed: Mon Oct 16 07:32:09 2017 -0400

----------------------------------------------------------------------
 .../gremlin/process/traversal/step/Scoping.java | 71 ++++++++++++++++++++
 1 file changed, 71 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/ea10316e/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/Scoping.java
----------------------------------------------------------------------
diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/Scoping.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/Scoping.java
index 683e661..65cac93 100644
--- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/Scoping.java
+++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/Scoping.java
@@ -30,6 +30,77 @@ import java.util.Set;
  * This interface is implemented by {@link Step} implementations that access labeled path steps, side-effects or
  * {@code Map} values by key, such as {@code select('a')} step. Note that a step like {@code project()} is non-scoping
  * because while it creates a {@code Map} it does not introspect them.
+ * <p/>
+ * There are four types of scopes:
+ * <ol>
+ *   <li>Current scope</li> — the current data referenced by the traverser (“path head”).
+ *   <li>Path scope</li> — a particular piece of data in the path of the traverser (“path history”).
+ *   <li>Side-effect scope</li> — a particular piece of data in the global traversal blackboard.
+ *   <li>Map scope</li> — a particular piece of data in the current scope map (“map value by key”).
+ * </ol>
+ *
+ * The current scope refers to the current object referenced by the traverser. That is, the {@code traverser.get()}
+ * object. Another way to think about the current scope is to think in terms of the path of the traverser where the
+ * current scope is the head of the path. With the math()-step, the variable {@code _} refers to the current scope.
+ *
+ * <pre>
+ * {@code
+ * gremlin> g.V().values("age").math("sin _")
+ * ==>-0.6636338842129675
+ * ==>0.956375928404503
+ * ==>0.5514266812416906
+ * ==>-0.428182669496151
+ * }
+ * </pre>
+ *
+ * The path scope refers to data previously seen by the traverser. That is, data in the traverser’s path history.
+ * Paths can be accessed by {@code path()}, however, individual parts of the path can be labeled using {@code as()}
+ * and accessed later via the path label name. Thus, in the traversal below, “a” and “b” refer to objects previously
+ * traversed by the traverser.
+ *
+ * <pre>
+ * {@code
+ * gremlin> g.V().as("a").out("knows").as("b”).
+ * math("a / b").by("age")
+ * ==>1.0740740740740742
+ * ==>0.90625
+ * }
+ * </pre>
+ *
+ * The side-effect scope refers objects in the global side-effects of the traversal. Side-effects are not local to the
+ * traverser, but instead, global to the traversal. In the traversal below you can see how “x” is being referenced in
+ * the math()-step and thus, the side-effect data is being used.
+ *
+ * <pre>
+ * {@code
+ * gremlin> g.withSideEffect("x",100).V().values("age").math("_ / x")
+ * ==>0.29
+ * ==>0.27
+ * ==>0.32
+ * ==>0.35
+ * }
+ * </pre>
+ *
+ * Map scope refers to objects within the current map object. Thus, its like current scope, but a bit “deeper.” In the
+ * traversal below the {@code project()}-step generates a map with keys “a” and “b”. The subsequent {@code math()}-step
+ * is then able to access the “a” and “b” values in the respective map and use them for the division operation.
+ *
+ * <pre>
+ * {@code gremlin>
+ * g.V().hasLabel("person”).
+ * project("a","b”).
+ *   by("age”).
+ *   by(bothE().count()).
+ * math("a / b")
+ * ==>9.666666666666666
+ * ==>27.0
+ * ==>10.666666666666666
+ * ==>35.0
+ * }
+ * </pre>
+ *
+ * Scoping is all about variable data access and forms the fundamental interface for access to the memory structures
+ * of Gremlin.
  *
  * @author Marko A. Rodriguez (http://markorodriguez.com)
  * @author Stephen Mallette (http://stephen.genoprime.com)