Clarify dateDiff() subtraction direction and result sign in docs - #3552
Merged
Conversation
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
Codecov Report✅ All modified and coverable lines are covered by tests. 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. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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==> -86400000output.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 thevalueanddateTraversalarguments.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.