[tinkerpop] branch master updated: Minor javadoc improvements for optimization strategies CTR

[sp...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git


The following commit(s) were added to refs/heads/master by this push:
     new 6400d2d  Minor javadoc improvements for optimization strategies CTR
     new 0a30b73  Merge branch 'tp34'
6400d2d is described below

commit 6400d2ddaec895907a27be0e0bbc32a9d046c70c
Author: Stephen Mallette <sp...@genoprime.com>
AuthorDate: Wed Jul 10 16:23:14 2019 -0400

    Minor javadoc improvements for optimization strategies CTR
---
 .../strategy/optimization/AdjacentToIncidentStrategy.java        | 6 ++++--
 .../traversal/strategy/optimization/FilterRankingStrategy.java   | 3 ++-
 .../strategy/optimization/IncidentToAdjacentStrategy.java        | 2 +-
 .../traversal/strategy/optimization/InlineFilterStrategy.java    | 9 +++++----
 4 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/optimization/AdjacentToIncidentStrategy.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/optimization/AdjacentToIncidentStrategy.java
index 2d19479..d8e538a 100644
--- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/optimization/AdjacentToIncidentStrategy.java
+++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/optimization/AdjacentToIncidentStrategy.java
@@ -42,10 +42,12 @@ import java.util.Set;
 
 /**
  * This strategy looks for vertex- and value-emitting steps followed by a {@link CountGlobalStep} and replaces the
- * pattern with an edge- or property-emitting step followed by a {@code CountGlobalStep}. Furthermore, if a vertex-
+ * pattern with an edge- or property-emitting step followed by a {@link CountGlobalStep}. Furthermore, if a vertex-
  * or value-emitting step is the last step in a {@code .has(traversal)}, {@code .and(traversal, ...)} or
  * {@code .or(traversal, ...)} child traversal, it is replaced by an appropriate edge- or property-emitting step.
- * <p/>
+ * Performing this replacement removes situations where the more expensive trip to an adjacent graph element (e.g.
+ * the vertex on the other side of an edge) can be satisfied by trips to incident graph elements (e.g. just the edge
+ * itself).
  *
  * @author Daniel Kuppitz (http://gremlin.guru)
  * @example <pre>
diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/optimization/FilterRankingStrategy.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/optimization/FilterRankingStrategy.java
index bec2502..9ae7c72 100644
--- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/optimization/FilterRankingStrategy.java
+++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/optimization/FilterRankingStrategy.java
@@ -44,7 +44,8 @@ import java.util.List;
 import java.util.Set;
 
 /**
- * FilterRankingStrategy reorders filter- and order-steps according to their rank. It will also do its best to push
+ * FilterRankingStrategy reorders filter- and order-steps according to their rank. Step ranks are defined within the
+ * strategy and indicate when it is reasonable for a step to move in front of another. It will also do its best to push
  * step labels as far "right" as possible in order to keep traversers as small and bulkable as possible prior to the
  * absolute need for path-labeling.
  *
diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/optimization/IncidentToAdjacentStrategy.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/optimization/IncidentToAdjacentStrategy.java
index 77e896c..c9871fb 100644
--- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/optimization/IncidentToAdjacentStrategy.java
+++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/optimization/IncidentToAdjacentStrategy.java
@@ -55,7 +55,7 @@ import java.util.Set;
  * <li>the traversal contains a {@code path} step</li>
  * <li>the traversal contains a lambda step</li>
  * </ul>
- * <p/>
+ * By re-writing the traversal in this fashion, the traversal eliminates unnecessary steps and becomes more normalized.
  *
  * @author Daniel Kuppitz (http://gremlin.guru)
  * @example <pre>
diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/optimization/InlineFilterStrategy.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/optimization/InlineFilterStrategy.java
index e2f154e..f5f980f 100644
--- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/optimization/InlineFilterStrategy.java
+++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/strategy/optimization/InlineFilterStrategy.java
@@ -54,10 +54,11 @@ import java.util.List;
 import java.util.Set;
 
 /**
- * InlineFilterStrategy analyzes filter-steps with child traversals that themselves are pure filters.
- * If the child traversals are pure filters then the wrapping parent filter is not needed and thus, the
- * children can be "inlined."
- * <p/>
+ * This strategy analyzes filter-steps with child traversals that themselves are pure filters. If the child traversals
+ * are pure filters then the wrapping parent filter is not needed and thus, the children can be "inlined." Normalizing
+ * pure filters with inlining reduces the number of variations of a filter that a graph provider may need to reason
+ * about when writing their own strategies. As a result, this strategy helps increase the likelihood that a provider's
+ * filtering optimization will succeed at re-writing the traversal.
  *
  * @author Marko A. Rodriguez (http://markorodriguez.com)
  * @example <pre>