(tinkerpop) branch master updated: Explain Pick.none and the fictional label in the Discard Step example

[sp...@apache.org]

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 a3574852c9 Explain Pick.none and the fictional label in the Discard Step example
a3574852c9 is described below

commit a3574852c9cde774d452176e66c8775758e7ce7d
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Thu Sep 10 18:48:25 2026 +0000

    Explain Pick.none and the fictional label in the Discard Step example
    
    The Discard Step example uses the bare none token, an invented bleep
    label, and assumes the modern graph's schema without comment, so a
    newcomer cannot work out why it emits only vadas and josh. Add a short
    paragraph that identifies none as Pick.none and the default branch,
    notes the qualified form for use outside the Gremlin Console, explains
    that bleep is intentionally fictional so software vertices fall through
    to option(none, discard()) and are removed, and cross-links the Choose
    Step and Branch Step sections for the full option() and Pick semantics.
    
    Assisted-by: Kiro:claude-opus-4.8
---
 docs/src/reference/the-traversal.asciidoc | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/src/reference/the-traversal.asciidoc b/docs/src/reference/the-traversal.asciidoc
index fa0e2b7829..781dda2c56 100644
--- a/docs/src/reference/the-traversal.asciidoc
+++ b/docs/src/reference/the-traversal.asciidoc
@@ -1917,6 +1917,15 @@ g.V().choose(T.label).
         option(none, discard())
 ----
 
+In the example above, `none` refers to `Pick.none`, a built-in constant that matches traversers satisfying no other
+`option()` and therefore acts as the default branch. The Gremlin Console resolves the bare `none` token to this
+constant automatically, while other environments use the qualified `Pick.none` form. The `"bleep"` label is
+intentionally fictional and matches no vertex in the "modern" graph, whose vertices carry only the "person" and
+"software" labels. The "software" vertices therefore match neither `"person"` nor `"bleep"`, fall through to
+`option(none, discard())`, and are silently removed, while "marko", the only vertex with outgoing "knows" edges, emits
+"vadas" and "josh". The <<choose-step>> and <<branch-step>> sections describe the full semantics of `option()` and the
+`Pick` tokens.
+
 It is also useful for traversals that are executed remotely where returning results is not useful and the traversal is
 only meant to generate side-effects. Choosing not to return results saves in serialization and network costs as the
 objects are filtered on the remote end and not returned to the client side. Typically, this step does not need to be