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 72f609f521 Clarify dateDiff() subtraction direction and result sign in
docs
72f609f521 is described below
commit 72f609f521110fd0509daeb31d5707e75cc36ac3
Author: Stephen Mallette <[email protected]>
AuthorDate: Thu Jul 23 16:46:42 2026 +0000
Clarify dateDiff() subtraction direction and result sign in docs
Document that dateDiff() computes the difference in epoch milliseconds as
the incoming traverser date minus the argument date, where a positive result
means the incoming date is later and a negative result means it is earlier.
Updates both the reference the-traversal.asciidoc dateDiff-step section
(adding
the direction/sign explanation alongside the example) and the provider
gremlin-semantics.asciidoc dateDiff() section (replacing the ambiguous
'subtracted with the incoming traverser' wording with an explicit order).
Assisted-by: Kiro:claude-opus-4.8
---
docs/src/dev/provider/gremlin-semantics.asciidoc | 10 ++++++----
docs/src/reference/the-traversal.asciidoc | 6 +++++-
2 files changed, 11 insertions(+), 5 deletions(-)
diff --git a/docs/src/dev/provider/gremlin-semantics.asciidoc
b/docs/src/dev/provider/gremlin-semantics.asciidoc
index 4c6a6525ec..86ff317f30 100644
--- a/docs/src/dev/provider/gremlin-semantics.asciidoc
+++ b/docs/src/dev/provider/gremlin-semantics.asciidoc
@@ -1476,7 +1476,9 @@
link:https://tinkerpop.apache.org/docs/x.y.z/reference/#dateAdd-step[reference]
[[dateDiff-step]]
=== dateDiff()
-*Description:* Returns the difference between two Dates in epoch time.
+*Description:* Returns the difference between two Dates in epoch time
(milliseconds), computed as the incoming
+traverser `DATETIME` minus the argument `DATETIME`. A positive result means
the incoming date is later than the
+argument date, while a negative result means the incoming date is earlier.
*Syntax:* `dateDiff(value: DATETIME)` | `dateDiff(dateTraversal:
Traversal<any, DATETIME>)`
@@ -1488,9 +1490,9 @@
link:https://tinkerpop.apache.org/docs/x.y.z/reference/#dateAdd-step[reference]
*Arguments:*
-* `value` - Date for subtraction.
-* `dateTraversal` - The `Traversal` value must resolve to a `DATETIME`. The
first result returned from the traversal will be
-subtracted with the incoming traverser.
+* `value` - The `DATETIME` to subtract from the incoming traverser (result =
incoming `DATETIME` - `value`).
+* `dateTraversal` - The `Traversal` value must resolve to a `DATETIME`. The
first result returned from the traversal
+is subtracted from the incoming traverser (result = incoming `DATETIME` -
traversal result).
*Modulation:*
diff --git a/docs/src/reference/the-traversal.asciidoc
b/docs/src/reference/the-traversal.asciidoc
index d1d4136d95..7524f64d87 100644
--- a/docs/src/reference/the-traversal.asciidoc
+++ b/docs/src/reference/the-traversal.asciidoc
@@ -1685,7 +1685,11 @@
link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gre
[[dateDiff-step]]
=== DateDiff Step
-The `dateDiff()`-step (*map*) returns the difference between two Dates in
epoch time in milliseconds.
+The `dateDiff()`-step (*map*) returns the difference between two Dates in
epoch time in milliseconds. The result is
+computed as the incoming traverser date minus the argument date. A positive
result means the incoming date is later
+than the argument date, while a negative result means the incoming date is
earlier. In the example below, the incoming
+date (`2023-08-02`) is one day earlier than the argument date (`2023-08-03`),
so the result is `-86400000`
+(one day in milliseconds).
If the incoming traverser is not a Date or OffsetDateTime, then an
`IllegalArgumentException` will be thrown.
[gremlin-groovy,modern]
