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 71d184d40aa93bdd52a218de3df1bacb601c25c3 Author: chaokunyang <[email protected]> AuthorDate: Mon Jul 27 10:36:20 2026 +0000 π synced local 'docs/guide/' with remote 'docs/guide/' --- docs/guide/csharp/external-types.md | 18 +++++++++++++----- docs/guide/csharp/supported-types.md | 3 +++ docs/guide/dart/external-types.md | 8 ++++++-- docs/guide/dart/schema-metadata.md | 11 +++++++---- docs/guide/swift/external-types.md | 4 ++++ 5 files changed, 33 insertions(+), 11 deletions(-) diff --git a/docs/guide/csharp/external-types.md b/docs/guide/csharp/external-types.md index d9678d5d38..1af23e7988 100644 --- a/docs/guide/csharp/external-types.md +++ b/docs/guide/csharp/external-types.md @@ -91,7 +91,8 @@ internal static class StatusSerializer The target enum's numeric values are authoritative. Do not copy its constants into the declaration. Every serialized numeric value must fit in the unsigned -32-bit Fory enum tag range. +32-bit Fory enum tag range. Cross-language peers must use matching explicit +enum tags, such as Java's `@ForyEnumId`. ## Registration and Root Values @@ -102,6 +103,7 @@ Fory fory = Fory.Builder().Build(); fory.Register<ThirdParty.User>(100); fory.Register<ThirdParty.Status>("example.Status"); +ThirdParty.User user = new() { Name = "Alice", Age = 30 }; byte[] bytes = fory.Serialize(user); ThirdParty.User decoded = fory.Deserialize<ThirdParty.User>(bytes); ``` @@ -128,6 +130,7 @@ public sealed class Group Root carrier composition also uses the ordinary typed API: ```csharp +ThirdParty.User user = new() { Name = "Alice", Age = 30 }; byte[] bytes = fory.Serialize(new List<ThirdParty.User> { user }); List<ThirdParty.User> decoded = @@ -151,7 +154,8 @@ typed roots. ## Declaration and Target Requirements An external structural serializer declaration must be a non-generic abstract -class containing only abstract get-only schema properties. Each property: +class containing only abstract get-only schema properties. Each serialized +property: - matches an accessible target field or property with the same case-sensitive name; @@ -165,13 +169,17 @@ nullability. Only members declared by the serializer are serialized; other target state keeps its normal default or derived behavior after deserialization. +Use `[ForyField(Ignore = true)]` on an additional declaration property when +non-serialized target storage still needs to contribute to the graph-memory +estimate. Public target fields are included automatically. + The target must be an accessible concrete class or struct with a legal parameterless construction path and writable state. Closed generic targets, such as `ThirdParty.Box<string>`, are supported; open generic targets are not. -Targets that require private access, readonly or init-only assignment, -constructor arguments, factories, member renaming, or value conversion require -a [manual serializer](manual-serializers.md). +Serialized members that require private access, readonly or init-only +assignment, constructor arguments, factories, member renaming, or value +conversion require a [manual serializer](manual-serializers.md). ## Schema Evolution diff --git a/docs/guide/csharp/supported-types.md b/docs/guide/csharp/supported-types.md index db6236377b..1b1eccdf78 100644 --- a/docs/guide/csharp/supported-types.md +++ b/docs/guide/csharp/supported-types.md @@ -82,6 +82,9 @@ This page summarizes built-in and generated type support in Apache Foryβ’ C#. - Manual serializer types registered through `Register<T, TSerializer>(...)` - `Union` / `Union2<...>` typed union support +`[ForyEnum]` numeric values are unsigned 32-bit wire tags and must be in the +range `0..uint.MaxValue`. + ## Dynamic Types Dynamic object payloads via `Serialize<object?>` / `Deserialize<object?>` support: diff --git a/docs/guide/dart/external-types.md b/docs/guide/dart/external-types.md index 0d9e96c6c5..38314a33bd 100644 --- a/docs/guide/dart/external-types.md +++ b/docs/guide/dart/external-types.md @@ -59,8 +59,12 @@ abstract final class UserSerializer { The declaration must be `abstract final`, cannot have type parameters, and must declare each schema field as `late final` without an initializer. Each -field name and Dart type, including nullability and generic arguments, must -exactly match an accessible getter on the target. +serialized field name and Dart type, including nullability and generic +arguments, must exactly match an accessible getter on the target. + +Public target fields count toward the graph-memory budget automatically. Use +`@ForyField(ignore: true)` on an extra declaration field to count other storage +without serializing it. Run the generator as usual: diff --git a/docs/guide/dart/schema-metadata.md b/docs/guide/dart/schema-metadata.md index 63d4da5952..9d189ffa85 100644 --- a/docs/guide/dart/schema-metadata.md +++ b/docs/guide/dart/schema-metadata.md @@ -28,7 +28,7 @@ The same annotations apply to fields in an ```dart @ForyField( - skip: false, // include the field; set true to exclude it + ignore: false, // include the field; set true to exclude it id: 10, // stable field ID for schema evolution nullable: true, // override nullability detection ref: true, // enable reference tracking for this field @@ -36,12 +36,15 @@ The same annotations apply to fields in an ) ``` -## `skip` +## `ignore` -Exclude a field from serialization entirely. Useful for cached, computed, or UI-only values that should not land in a persisted or transmitted message. +Exclude a field from serialization entirely. Useful for cached, computed, or +UI-only values that should not land in a persisted or transmitted message. The +field still contributes to graph-memory accounting; because it has no wire +representation, do not combine `ignore` with other `ForyField` options. ```dart -@ForyField(skip: true) +@ForyField(ignore: true) String cachedDisplayName = ''; ``` diff --git a/docs/guide/swift/external-types.md b/docs/guide/swift/external-types.md index 5307bf1f4a..c1e8b80863 100644 --- a/docs/guide/swift/external-types.md +++ b/docs/guide/swift/external-types.md @@ -84,6 +84,10 @@ The target class must have an accessible zero-argument initializer and writable serialized properties. These requirements allow Fory to preserve shared and circular references. +Swift budgets only fields listed in this declaration. Add +`@ForyField(ignore: true)` fields for substantial omitted storage; they count +toward the graph budget but are not serialized. + Use a manual serializer if the class is immutable, requires constructor arguments, or cannot be safely observed before all fields are assigned. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
