Merge branch '3.7-dev'

Author: spmallette

docs/src/reference/the-traversal.asciidoc

@@ -1418,8 +1418,8 @@ g.V().elementMap('name')
 g.V().dedup().by(label).values('name')
 ----
 
-Finally, if `dedup()` is provided an array of strings, then it will ensure that the de-duplication is not with respect
-to the current traverser object, but to the path history of the traverser.
+If `dedup()` is provided an array of strings, then it will ensure that the de-duplication is not with respect to the
+current traverser object, but to the path history of the traverser.
 
 [gremlin-groovy,modern]
 ----
@@ -1433,6 +1433,37 @@ g.V().as('a').both().as('b').both().as('c').
 <1> If the current `a` and `b` combination has been seen previously, then filter the traverser.
 <2> The "age" property is not <<by-step,productive>> for all vertices and therefore those values are filtered.
 
+The `dedup()` step can work on many different types of objects. One object in particular can need a bit of explanation.
+If you use `dedup()` on a `Path` object there is a chance that you may get some unexpected results. Consider the
+following example which forcibly generates duplicate path results in the first traversal and in the second applies
+`dedup()` to remove them:
+
+[gremlin-groovy,modern]
+----
+g.V().union(out().path(), out().path())
+g.V().union(out().path(), out().path()).dedup()
+----
+
+The `dedup()` step checks the equality of the paths by examining the equality of the objects on the `Path` (in this case
+vertices), but also on any path labels. In the prior example, there weren't any path labels so `dedup()` behaved as
+expected. In the next example, note the difference in the results if a label is added for one `Path` but not the other:
+
+[gremlin-groovy,modern]
+----
+g.V().union(out().as('x').path(), out().path())
+g.V().union(out().as('x').path(), out().path()).dedup()
+----
+
+The prior example shows how `dedup()` does not have the same effect when a path label is in place. In this contrived
+example the answer is simple: remove the `as('x')`. If in the real world, it is not possible to remove the label, the
+workaround is to deconstruct the `Path` into a `List` to drop the label. In this way, `dedup()` is just comparing `List`
+objects and the objects in the `Path`.
+
+[gremlin-groovy,modern]
+----
+g.V().union(out().as('x').path(), out().path()).map(unfold().fold()).dedup()
+----
+
 *Additional References*
 
 link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#dedup(org.apache.tinkerpop.gremlin.process.traversal.Scope,java.lang.String...)++[`dedup(Scope,String...)`],
@@ -5325,7 +5356,7 @@ First, it is important to recognize that there is a bit of a difference in behav
 becomes its composite `Map.Entry` objects as is typical in Java. The following example demonstrates the basic name/value
 pairs that returned:
 
-[groovy,modern]
+[gremlin-groovy,modern]
 ----
 g.V().valueMap('name','age').unfold()
 ----
@@ -5380,7 +5411,7 @@ Display stack trace? [yN]
 While this problem might be solved in future versions, the workaround for both cases is to use
 <<constant-step,constant()>> as shown in the following example:
 
-[groovy,modern]
+[gremlin-groovy,modern]
 ----
 g.V().hasLabel('person').both().group().by(constant(id))
 g.V().hasLabel('person').both().group().by('age').select(constant(32))