Skip to content

Clarify addE()-step from()/to() semantics in reference docs - #3609

Merged
spmallette merged 1 commit into
apache:masterfrom
spmallette:tp-docs-adde-step
Aug 4, 2026
Merged

Clarify addE()-step from()/to() semantics in reference docs#3609
spmallette merged 1 commit into
apache:masterfrom
spmallette:tp-docs-adde-step

Conversation

@spmallette

Copy link
Copy Markdown
Contributor

The AddE Step section of the reference documentation had a few gaps that made the from()/to() behavior hard to learn from the examples alone:

  • Callouts 5 and 6 carried identical prose ("directed (detached) vertex references") even though they show fundamentally different patterns. g.V(vMarko).addE('knows').to(vPeter) uses the incoming traverser as the implicit from-vertex, whereas g.addE('knows').from(vMarko).to(vPeter) spawns the edge from g — where there is no traverser to act as a default endpoint, so both endpoints must be stated explicitly. The two callouts are now distinct and explain that distinction.
  • The from()/to() argument forms were demonstrated but never stated as a rule. Added a short introductory note documenting the two canonical forms (a step-label string and a child traversal), and clarifying that passing a Vertex object directly is convenience syntax exposed by the language variant (e.g. Gremlin-Java, which resolves the Vertex to its id) rather than canonical Gremlin.
  • The cumulative nature of the example block (each addE() persists and edge ids accumulate line to line) was never mentioned; added a note.
  • Callout 2's stated edge direction was reversed: the query produces lop->josh and ripple->josh, but the prose read "from the josh-vertex to the lop- and ripple-vertices." Corrected.

Only the AddE Step section prose/callouts were touched; the live examples are unchanged and still render the same output.

Distinguish the two addE() endpoint patterns that previously shared
identical callout prose: using the incoming traverser as the implicit
from-vertex (g.V(vMarko).addE('knows').to(vPeter)) versus spawning the
edge from g, which has no traverser and so requires both from() and
to() to be stated explicitly.

Add an introductory note documenting the two canonical from()/to()
argument forms (a step-label string and a child traversal), that
passing a Vertex object directly is language-variant convenience
syntax rather than canonical Gremlin, and that the examples run
cumulatively against the same graph so edges accumulate across the
block. Also correct the createdBy example callout, whose stated edge
direction was reversed relative to the actual lop->josh and
ripple->josh edges.

Assisted-by: Kiro:claude-opus-4.8
@codecov-commenter

codecov-commenter commented Aug 4, 2026

Copy link
Copy Markdown

Codecov Report

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

Additional details and impacted files
@@             Coverage Diff              @@
##             master    #3609      +/-   ##
============================================
+ Coverage     76.35%   76.48%   +0.12%     
- Complexity    13424    14299     +875     
============================================
  Files          1012     1036      +24     
  Lines         60341    64620    +4279     
  Branches       7075     7664     +589     
============================================
+ Hits          46076    49426    +3350     
- Misses        11548    12102     +554     
- 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.

@spmallette
spmallette merged commit 9cb7d61 into apache:master Aug 4, 2026
28 checks passed
@spmallette
spmallette deleted the tp-docs-adde-step branch August 4, 2026 19:26
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