This is an automated email from the ASF dual-hosted git repository. chaokunyang pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 5c0913da66b271ff9d58171c1337f7e594ae861a Author: chaokunyang <[email protected]> AuthorDate: Wed May 13 11:15:30 2026 +0000 🔄 synced local 'docs/guide/' with remote 'docs/guide/' --- docs/guide/cpp/field-configuration.md | 9 +++++---- docs/guide/csharp/field-configuration.md | 2 +- docs/guide/go/struct-tags.md | 2 +- docs/guide/go/troubleshooting.md | 4 ++-- docs/guide/java/field-configuration.md | 7 ++++--- docs/guide/python/field-configuration.md | 4 ++-- docs/guide/rust/field-configuration.md | 4 ++-- 7 files changed, 17 insertions(+), 15 deletions(-) diff --git a/docs/guide/cpp/field-configuration.md b/docs/guide/cpp/field-configuration.md index 02029453ac..070e9f2d96 100644 --- a/docs/guide/cpp/field-configuration.md +++ b/docs/guide/cpp/field-configuration.md @@ -46,16 +46,17 @@ or add virtual dispatch on the serialization path. FORY_STRUCT(DataV2, id, (timestamp, fory::F().tagged()), version); ``` -`fory::F(id)` uses id-mode field identity: +`fory::F(id)` uses explicit id-based field identity. IDs must be +non-negative: ```cpp FORY_STRUCT(DataV2, (id, fory::F(0)), (timestamp, fory::F(1).tagged()), (version, fory::F(2))); ``` -A struct must use exactly one identity mode. If any field uses `fory::F(id)`, -every field in that `FORY_STRUCT` must use `fory::F(id)`. Mixed name/id mode is a -compile-time error. +Fields without explicit IDs still use their snake_case field names. Explicit +IDs sort before name-based fields within the same protocol field group, so a +single `FORY_STRUCT` may mix `fory::F(id)`, `fory::F()`, and bare fields. ## Scalar Encoding diff --git a/docs/guide/csharp/field-configuration.md b/docs/guide/csharp/field-configuration.md index c68eeac4a1..778054c80e 100644 --- a/docs/guide/csharp/field-configuration.md +++ b/docs/guide/csharp/field-configuration.md @@ -23,7 +23,7 @@ This page covers field-level serializer configuration for C# generated serialize ## `[ForyObject]` and `[ForyField]` -Use `[ForyObject]` to enable source-generated serializers. Use `[ForyField]` to assign an optional stable field id or to override the Fory schema type used for a field. +Use `[ForyObject]` to enable source-generated serializers. Use `[ForyField]` to assign an optional stable non-negative field id or to override the Fory schema type used for a field. ```csharp using Apache.Fory; diff --git a/docs/guide/go/struct-tags.md b/docs/guide/go/struct-tags.md index 00c8dc7826..c383a85f86 100644 --- a/docs/guide/go/struct-tags.md +++ b/docs/guide/go/struct-tags.md @@ -336,7 +336,7 @@ type User struct { | ---------- | ------- | ------------------------ | | `nullable` | `false` | Use pointer types (`*T`) | | `ref` | `false` | Add `fory:"ref"` tag | -| `id` | `-1` | Add `fory:"id=N"` tag | +| `id` | omitted | Add `fory:"id=N"` tag | ## Best Practices diff --git a/docs/guide/go/troubleshooting.md b/docs/guide/go/troubleshooting.md index f87ce5fc25..345c03563a 100644 --- a/docs/guide/go/troubleshooting.md +++ b/docs/guide/go/troubleshooting.md @@ -211,10 +211,10 @@ f2 := fory.New(fory.WithTrackRef(true)) // Must match! **Common causes**: -1. **Invalid tag ID**: ID must be >= -1 +1. **Invalid tag ID**: ID must be non-negative ```go -// Wrong: negative ID (other than -1) +// Wrong: negative ID type Bad struct { Field int `fory:"id=-5"` } diff --git a/docs/guide/java/field-configuration.md b/docs/guide/java/field-configuration.md index ef8bebd1bb..7992f4afc5 100644 --- a/docs/guide/java/field-configuration.md +++ b/docs/guide/java/field-configuration.md @@ -84,7 +84,7 @@ public class User { | Parameter | Type | Default | Description | | ---------- | --------- | ------- | -------------------------------------- | -| `id` | `int` | `-1` | Field tag ID (-1 = use field name) | +| `id` | `int` | `-1` | Non-negative field tag ID, or no ID | | `nullable` | `boolean` | `false` | Whether the field can be null | | `ref` | `boolean` | `false` | Enable reference tracking | | `dynamic` | `Dynamic` | `AUTO` | Control polymorphism for struct fields | @@ -117,8 +117,9 @@ public class User { **Notes**: - IDs must be unique within a class -- IDs must be >= 0 (use -1 to use field name encoding, which is the default) -- If not specified, field name is used in metadata (larger overhead) +- IDs must be >= 0 when configured +- If not specified, the annotation default `-1` is ignored and field name is used in metadata + (larger overhead) **Without field IDs** (field names used in metadata): diff --git a/docs/guide/python/field-configuration.md b/docs/guide/python/field-configuration.md index e223d5de21..66b7f52ad8 100644 --- a/docs/guide/python/field-configuration.md +++ b/docs/guide/python/field-configuration.md @@ -72,7 +72,7 @@ class User: | Parameter | Type | Default | Description | | ----------------- | -------- | --------- | ------------------------------------ | -| `id` | `int` | `-1` | Field tag ID (-1 = use field name) | +| `id` | `int` | omitted | Non-negative field tag ID | | `nullable` | `bool` | `False` | Whether the field can be null | | `ref` | `bool` | `False` | Enable reference tracking | | `ignore` | `bool` | `False` | Exclude field from serialization | @@ -103,7 +103,7 @@ class User: **Notes**: - IDs must be unique within a class -- IDs must be >= 0 (use -1 to use field name encoding, which is the default) +- IDs must be >= 0 - If not specified, field name is used in metadata (larger overhead) **Without field IDs** (field names used in metadata): diff --git a/docs/guide/rust/field-configuration.md b/docs/guide/rust/field-configuration.md index eb7027b1ca..c5cc57b701 100644 --- a/docs/guide/rust/field-configuration.md +++ b/docs/guide/rust/field-configuration.md @@ -83,7 +83,7 @@ struct User { **Notes**: - IDs must be unique within a struct -- IDs must be >= 0 (use -1 to explicitly opt-out of tag ID encoding) +- IDs must be non-negative - If not specified, field name is used in metadata (larger overhead) ### Skipping Fields (`skip`) @@ -317,7 +317,7 @@ struct Bad { // Error: invalid id value #[derive(ForyStruct)] struct Bad2 { - #[fory(id = -2)] // Compile error: id must be >= -1 + #[fory(id = -1)] // Compile error: id must be non-negative field: String, } --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
