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
commit 7ce5e2c2f90dcc63e38e447815e8ac44a120120c Author: Stephen Mallette <[email protected]> AuthorDate: Sat Jun 27 12:06:03 2026 +0000 Record semantics-doc conventions in tinker-doc skill CTR Capture three non-obvious conventions established during the recent language-agnostic alignment of `gremlin-semantics.asciidoc`: - The `GType` enum is the canonical type vocabulary. Name the specific enum entries so authors don't reinvent abstractions like `int32` or `BigInteger`. - Type definitions belong in `== Types`; per-type Equality, Comparability, and Orderability behavior belongs in the Comparability chapter. Do not duplicate definitions across the two. - The `Java reference exception` column of the Errors table is the one intentional Java reference in the document; do not "fix" it. Also note that an `*Exceptions:*` edit should be verified against the step's source class. Assisted-by: Kiro:claude-opus-4-7 --- .skills/tinker-doc/references/books-and-voice.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/.skills/tinker-doc/references/books-and-voice.md b/.skills/tinker-doc/references/books-and-voice.md index 04c903e6ae..a0baa14b8f 100644 --- a/.skills/tinker-doc/references/books-and-voice.md +++ b/.skills/tinker-doc/references/books-and-voice.md @@ -247,7 +247,13 @@ functions in normative prose. The reference implementation is linked from each step's `See:` block, and that is the appropriate place for any Java-flavored specifics. For exceptions, name the TinkerPop error category (`Argument Error`, `State Error`, `Type Error`, `Arithmetic Error`, `Unsupported Operation`) rather -than a Java exception class. +than a Java exception class. For types, use the `GType` enum names (`STRING`, +`INT`, `LONG`, `BIGINT`, `BIGDECIMAL`, `FLOAT`, `DOUBLE`, `BOOLEAN`, `UUID`, +`DATETIME`, `DURATION`, `BINARY`, `CHAR`, `NULL`, `NUMBER`, `LIST`, `SET`, `MAP`, +plus graph types). Type definitions live in `== Types`; per-type Equality, +Comparability, and Orderability behavior lives in the Comparability chapter. Do +not duplicate definitions across the two. The `Java reference exception` column +of the Errors table is the one intentional Java reference in the document. The document has two parts. The conceptual sections near the top (equality, comparability, orderability, equivalence, type promotion) specify the @@ -291,7 +297,8 @@ A new overload usually means adding its signature to `*Syntax:*` and describing the new argument under `*Arguments:*`. A semantic change usually means revising `*Considerations:*` or `*Exceptions:*`. Match a nearby existing step rather than inventing a new structure, and fill the gap when documenting a step that has no -entry yet. +entry yet. When editing an `*Exceptions:*` section, verify the claim against the +step's source class. ---
