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 1352e9523d Improve loops-step docs with output and clearer semantics
1352e9523d is described below
commit 1352e9523df123fb9cfab797475792dd02f87129
Author: stepmall <[email protected]>
AuthorDate: Sat Jul 25 11:45:11 2026 +0000
Improve loops-step docs with output and clearer semantics
Expand the Loops Step section of the traversal reference so the example
is self-explanatory. Clarify that loops() returns 0 before the first
iteration and counts completed (0-based) iterations, explain that an
emit() placed before repeat() is evaluated on every pass including the
zeroth, note that the no-argument or() acts as an infix disjunction
(cross-referencing the Or Step), and describe how the repeat()
terminates when no times()/until() is given.
Assisted-by: Kiro:claude-opus-4.8
---
docs/src/reference/the-traversal.asciidoc | 14 +++++++++++++-
1 file changed, 13 insertions(+), 1 deletion(-)
diff --git a/docs/src/reference/the-traversal.asciidoc
b/docs/src/reference/the-traversal.asciidoc
index cda8568bf5..5110082186 100644
--- a/docs/src/reference/the-traversal.asciidoc
+++ b/docs/src/reference/the-traversal.asciidoc
@@ -2934,13 +2934,25 @@
link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gre
[[loops-step]]
=== Loops Step
-The `loops()`-step (*map*) extracts the number of times the `Traverser` has
gone through the current loop.
+The `loops()`-step (*map*) returns the number of times the `Traverser` has
completed the current
+`<<repeat-step,repeat()>>` loop. It returns `0` before the first iteration and
counts *completed* loop iterations
+(i.e. it is 0-based), incrementing after each pass through the
repeat-traversal.
[gremlin-groovy,modern]
----
g.V().emit(__.has("name",
"marko").or().loops().is(2)).repeat(__.out()).values("name")
----
+In the example above, `emit()` is placed *before* `<<repeat-step,repeat()>>`,
so its predicate is evaluated on the
+traversers prior to entering the repeat-traversal on every pass, including the
zeroth one where `loops()` is still
+`0`. On that initial pass the predicate matches "marko" (via the `has()`
check), which is why "marko" appears in the
+output before the loop has executed. The predicate also matches any traverser
that has completed two loops
+(`loops().is(2)`), which emits "ripple" and "lop" — the vertices reached after
two `out()` hops. The `or()` with no
+arguments is an infix disjunction that joins the preceding `has()` traversal
with the following `loops().is(2)`
+traversal (see <<or-step,`or()`>>). Because the traversal declares neither
`times()` nor `until()`, the `repeat()`
+terminates on its own once `out()` produces no further traversers (i.e. when a
sink vertex with no outgoing edges is
+reached).
+
*Additional References*
link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#loops()++[`loops()`],
