Skip to content

Clarify dateDiff() subtraction direction and result sign in docs - #3552

Merged
spmallette merged 1 commit into
apache:masterfrom
spmallette:docs-datediff-direction
Jul 23, 2026
Merged

Clarify dateDiff() subtraction direction and result sign in docs#3552
spmallette merged 1 commit into
apache:masterfrom
spmallette:docs-datediff-direction

Conversation

@spmallette

Copy link
Copy Markdown
Contributor

The dateDiff() documentation described the step as returning "the difference between two Dates" but never stated which operand is subtracted from which, so the sign of the result was unexplained. A newcomer running the reference example sees a negative value with no indication of why.

This change documents the direction and sign in both places that describe the step:

  • docs/src/reference/the-traversal.asciidoc (dateDiff-step): adds prose stating the result is computed 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, and explains why the example returns -86400000 (the incoming date is one day earlier than the argument). The live example block already renders its ==> -86400000 output.
  • docs/src/dev/provider/gremlin-semantics.asciidoc (dateDiff()): updates the Description to state the same direction and sign meaning, and replaces the ambiguous "The first result returned from the traversal will be subtracted with the incoming traverser" wording with an explicit "result = incoming DATETIME - argument" formulation for both the value and dateTraversal arguments.

This is a documentation-only clarification; the behavior is unchanged and was verified against DateDiffStep (Duration.between(argument, incoming)). The docs build renders both sections cleanly.

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
@spmallette
spmallette merged commit 72f609f into apache:master Jul 23, 2026
6 checks passed
@spmallette
spmallette deleted the docs-datediff-direction branch July 23, 2026 16:58
@codecov-commenter

codecov-commenter commented Jul 23, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.47%. Comparing base (a28cd1f) to head (24a3229).
⚠️ Report is 346 commits behind head on master.

Additional details and impacted files
@@             Coverage Diff              @@
##             master    #3552      +/-   ##
============================================
+ Coverage     76.35%   76.47%   +0.11%     
- Complexity    13424    14288     +864     
============================================
  Files          1012     1036      +24     
  Lines         60341    64561    +4220     
  Branches       7075     7656     +581     
============================================
+ Hits          46076    49371    +3295     
- Misses        11548    12098     +550     
- Partials       2717     3092     +375     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants