(fory-site) branch main updated: 🔄 synced local 'docs/guide/' with remote 'docs/guide/'

[chaokunyang]

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


The following commit(s) were added to refs/heads/main by this push:
     new 3435ddfa20 🔄 synced local 'docs/guide/' with remote 'docs/guide/'
3435ddfa20 is described below

commit 3435ddfa2024402c8e0093855f4f5c1199815c04
Author: chaokunyang <shawn.ck.y...@gmail.com>
AuthorDate: Fri Jul 3 16:55:59 2026 +0000

    🔄 synced local 'docs/guide/' with remote 'docs/guide/'
---
 docs/guide/go/codegen.md              | 430 ----------------------------------
 docs/guide/go/grpc-support.md         |   2 +-
 docs/guide/go/index.md                |   4 +-
 docs/guide/go/native-serialization.md |   6 +-
 docs/guide/go/thread-safety.md        |   2 +-
 docs/guide/go/troubleshooting.md      |   8 +-
 6 files changed, 7 insertions(+), 445 deletions(-)

diff --git a/docs/guide/go/codegen.md b/docs/guide/go/codegen.md
deleted file mode 100644
index 5900097244..0000000000
--- a/docs/guide/go/codegen.md
+++ /dev/null
@@ -1,430 +0,0 @@
----
-title: Code Generation
-sidebar_position: 11
-id: codegen
-license: |
-  Licensed to the Apache Software Foundation (ASF) under one or more
-  contributor license agreements.  See the NOTICE file distributed with
-  this work for additional information regarding copyright ownership.
-  The ASF licenses this file to You under the Apache License, Version 2.0
-  (the "License"); you may not use this file except in compliance with
-  the License.  You may obtain a copy of the License at
-
-     http://www.apache.org/licenses/LICENSE-2.0
-
-  Unless required by applicable law or agreed to in writing, software
-  distributed under the License is distributed on an "AS IS" BASIS,
-  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-  See the License for the specific language governing permissions and
-  limitations under the License.
----
-
-:::warning Experimental Feature
-Code generation is an **experimental** feature in Fory Go. The API and 
behavior may change in future releases. The standard dynamic serialization path 
remains the stable, recommended approach for most use cases.
-:::
-
-Fory Go provides optional ahead-of-time (AOT) code generation for 
performance-critical paths. This generates dedicated serializers ahead of time 
and adds compile-time shape checks.
-
-## Why Code Generation?
-
-| Aspect      | Standard Path      | Code Generation        |
-| ----------- | ------------------ | ---------------------- |
-| Setup       | Zero configuration | Requires `go generate` |
-| Performance | Excellent          | Better on hot paths    |
-| Type Safety | Runtime validation | Compile-time checks    |
-| Maintenance | Automatic          | Requires regeneration  |
-
-**Use code generation when**:
-
-- Maximum performance is required
-- Compile-time type safety is important
-- Hot paths are performance-critical
-
-**Use the standard path when**:
-
-- Simple setup is preferred
-- Types change frequently
-- Dynamic typing is needed
-- Code generation complexity is undesirable
-
-## Installation
-
-Install the `fory` generator binary:
-
-```bash
-go install github.com/apache/fory/go/fory/cmd/fory@latest
-
-GO111MODULE=on go get -u github.com/apache/fory/go/fory/cmd/fory
-```
-
-Ensure `$GOBIN` or `$GOPATH/bin` is in your `PATH`.
-
-## Basic Usage
-
-### Step 1: Annotate Structs
-
-Add the `//fory:generate` comment above structs:
-
-```go
-package models
-
-//fory:generate
-type User struct {
-    ID   int64  `json:"id"`
-    Name string `json:"name"`
-}
-
-//fory:generate
-type Order struct {
-    ID       int64
-    Customer string
-    Total    float64
-}
-```
-
-### Step 2: Add Go Generate Directive
-
-Add a `go:generate` directive (once per file or package):
-
-```go
-//go:generate fory -file models.go
-```
-
-Or for the entire package:
-
-```go
-//go:generate fory -pkg .
-```
-
-### Step 3: Run Code Generation
-
-```bash
-go generate ./...
-```
-
-This creates `models_fory_gen.go` with generated serializers.
-
-## Generated Code Structure
-
-The generator creates:
-
-### Type Snapshot
-
-A compile-time check to detect struct changes:
-
-```go
-// Snapshot of User's underlying type at generation time
-type _User_expected struct {
-    ID   int64
-    Name string
-}
-
-// Compile-time check: fails if User no longer matches
-var _ = func(x User) { _ = _User_expected(x) }
-```
-
-### Serializer Implementation
-
-Strongly-typed serialization methods:
-
-```go
-type User_ForyGenSerializer struct{}
-
-func NewSerializerFor_User() fory.Serializer {
-    return &User_ForyGenSerializer{}
-}
-
-func (User_ForyGenSerializer) WriteTyped(ctx *fory.WriteContext, v *User) 
error {
-    buf := ctx.Buffer()
-    buf.WriteInt64(v.ID)
-    ctx.WriteString(v.Name)
-    return nil
-}
-
-func (User_ForyGenSerializer) ReadTyped(ctx *fory.ReadContext, v *User) error {
-    err := ctx.Err()
-    buf := ctx.Buffer()
-    v.ID = buf.ReadInt64(err)
-    v.Name = ctx.ReadString()
-    if ctx.HasError() {
-        return ctx.TakeError()
-    }
-    return nil
-}
-```
-
-### Auto-Registration
-
-Serializers are registered in `init()`:
-
-```go
-func init() {
-    fory.RegisterSerializerFactory((*User)(nil), NewSerializerFor_User)
-}
-```
-
-## Command-Line Options
-
-### File-Based Generation
-
-Generate for a specific file:
-
-```bash
-fory -file models.go
-```
-
-### Package-Based Generation
-
-Generate for a package:
-
-```bash
-fory -pkg ./models
-```
-
-### Explicit Types
-
-Specify types explicitly:
-
-```bash
-fory -pkg ./models -type "User,Order"
-```
-
-### Force Regeneration
-
-Force regeneration even if up-to-date:
-
-```bash
-fory --force -file models.go
-```
-
-## When to Regenerate
-
-Regenerate when any of these change:
-
-- Field additions, removals, or renames
-- Field type changes
-- Struct tag changes
-- New structs with `//fory:generate`
-
-### Automatic Detection
-
-Fory includes a compile-time guard:
-
-```go
-// If struct changed, this fails to compile
-var _ = func(x User) { _ = _User_expected(x) }
-```
-
-If you forget to regenerate, the build fails with a clear message.
-
-### Auto-Retry
-
-When invoked via `go generate`, the generator detects stale code and retries:
-
-1. Detects compile error from guard
-2. Removes stale generated file
-3. Regenerates fresh code
-
-## Supported Types
-
-Code generation supports:
-
-- All primitive types (`bool`, `int*`, `uint*`, `float*`, `string`)
-- Slices of primitives and structs
-- Maps with supported key/value types
-- Nested structs (must also be generated)
-- Pointers to structs
-
-### Nested Structs
-
-All nested structs must also have `//fory:generate`:
-
-```go
-//fory:generate
-type Address struct {
-    City    string
-    Country string
-}
-
-//fory:generate
-type Person struct {
-    Name    string
-    Address Address  // Address must also be generated
-}
-```
-
-## CI/CD Integration
-
-### Check In Generated Code
-
-**Recommended for libraries**:
-
-```bash
-go generate ./...
-git add *_fory_gen.go
-git commit -m "Regenerate Fory serializers"
-```
-
-**Pros**: Consumers can build without generator; reproducible builds
-**Cons**: Larger diffs; must remember to regenerate
-
-### Generate in Pipeline
-
-**Recommended for applications**:
-
-```yaml
-steps:
-  - run: go install github.com/apache/fory/go/fory/cmd/fory@latest
-  - run: go generate ./...
-  - run: go build ./...
-```
-
-## Usage with Generated Code
-
-Generated code integrates transparently:
-
-```go
-f := fory.New(fory.WithXlang(true))
-
-// Fory automatically uses generated serializer if available
-user := &User{ID: 1, Name: "Alice"}
-data, _ := f.Serialize(user)
-
-var result User
-f.Deserialize(data, &result)
-```
-
-No code changes needed - registration happens in `init()`.
-
-## Mixing Generated and Non-Generated
-
-You can mix approaches:
-
-```go
-//fory:generate
-type HotPathStruct struct {
-    // Performance-critical, use codegen
-}
-
-type ColdPathStruct struct {
-    // Not annotated, uses the standard dynamic serializer
-}
-```
-
-## Limitations
-
-### Experimental Status
-
-- API may change
-- Not all edge cases tested
-- May have undiscovered bugs
-
-### Not Supported
-
-- Interface fields (dynamic types)
-- Recursive types without pointers
-- Private (unexported) fields
-- Custom serializers
-
-### Standard Path Fallback
-
-If generated serializers are unavailable, Fory falls back to the standard 
serializer path:
-
-```go
-// If User_ForyGenSerializer is not linked in, Fory uses the standard path
-f.Serialize(&User{})
-```
-
-## Troubleshooting
-
-### "fory: command not found"
-
-Ensure the binary is in PATH:
-
-```bash
-export PATH=$PATH:$(go env GOPATH)/bin
-```
-
-### Compile Error After Struct Change
-
-Regenerate:
-
-```bash
-go generate ./...
-```
-
-Or force:
-
-```bash
-fory --force -file yourfile.go
-```
-
-### Generated Code Out of Sync
-
-The compile-time guard catches this:
-
-```
-cannot use x (variable of type User) as type _User_expected in argument
-```
-
-Run `go generate` to fix.
-
-## Example Project Structure
-
-```
-myproject/
-├── models/
-│   ├── models.go           # Struct definitions
-│   ├── models_fory_gen.go  # Generated code
-│   └── generate.go         # go:generate directive
-├── main.go
-└── go.mod
-```
-
-**models/generate.go**:
-
-```go
-package models
-
-//go:generate fory -pkg .
-```
-
-**models/models.go**:
-
-```go
-package models
-
-//fory:generate
-type User struct {
-    ID   int64
-    Name string
-}
-```
-
-## FAQ
-
-### Is codegen required?
-
-No. The standard serializer path works without code generation.
-
-### Does generated code work across Go versions?
-
-Yes. Generated code is plain Go with no version-specific features.
-
-### Can I mix generated and non-generated types?
-
-Yes. Fory automatically uses generated serializers when available.
-
-### How do I update generated code?
-
-Run `go generate ./...` after struct changes.
-
-### Should I commit generated files?
-
-For libraries: yes. For applications: either works.
-
-## Related Topics
-
-- [Basic Serialization](basic-serialization.md)
-- [Configuration](configuration.md)
-- [Troubleshooting](troubleshooting.md)
diff --git a/docs/guide/go/grpc-support.md b/docs/guide/go/grpc-support.md
index 4c221dc90e..c921ed433f 100644
--- a/docs/guide/go/grpc-support.md
+++ b/docs/guide/go/grpc-support.md
@@ -1,6 +1,6 @@
 ---
 title: gRPC Support
-sidebar_position: 13
+sidebar_position: 12
 id: grpc_support
 license: |
   Licensed to the Apache Software Foundation (ASF) under one or more
diff --git a/docs/guide/go/index.md b/docs/guide/go/index.md
index 2cf4ebaf40..1a57278b6d 100644
--- a/docs/guide/go/index.md
+++ b/docs/guide/go/index.md
@@ -19,14 +19,14 @@ license: |
   limitations under the License.
 ---
 
-Apache Fory Go is a high-performance serialization library for Go. It supports 
xlang mode for cross-language payloads and native mode for Go-only payloads, 
with automatic object graph serialization, circular references, polymorphism, 
and schema-aware serializers.
+Apache Fory Go is a high-performance serialization library for Go. It supports 
xlang mode for cross-language payloads and native mode for Go-only payloads, 
with reflection-based object graph serialization, circular references, 
polymorphism, and schema-aware struct handling.
 
 ## Why Fory Go?
 
 - **High Performance**: Fast serialization and optimized binary protocols
 - **Xlang**: Seamless data exchange with Java, Python, C++, Rust,
   JavaScript/TypeScript, C#, Swift, Dart, Scala, and Kotlin
-- **Automatic Serialization**: No IDL definitions or schema compilation 
required
+- **Automatic Serialization**: Serialize Go structs directly with reflection
 - **Reference Tracking**: Built-in support for circular references and shared 
objects
 - **Type Safety**: Strong typing with schema-aware serializers
 - **Schema Evolution**: Compatible mode for forward/backward compatibility
diff --git a/docs/guide/go/native-serialization.md 
b/docs/guide/go/native-serialization.md
index 5e74d88b4e..1fce23d30f 100644
--- a/docs/guide/go/native-serialization.md
+++ b/docs/guide/go/native-serialization.md
@@ -38,7 +38,7 @@ Use native serialization when:
   the writer.
 - You want compatible schema evolution for Go-only rolling deployments without 
committing to a
   cross-language type mapping.
-- You are using reflection or code-generated serializers for Go structs that 
never leave Go.
+- You are using Go reflection-based serializers for structs that never leave 
Go.
 
 ## Create a Native-Mode Fory Instance
 
@@ -126,7 +126,7 @@ Native serialization keeps Go data in Go-native form:
 - Pointers and nil values, including nil slices and maps.
 - Interfaces and dynamic values when registered serializers can resolve their 
concrete types.
 - Time values such as `time.Time` and `time.Duration`.
-- Reflection-based and code-generated serializers.
+- Reflection-based serializers.
 
 Use [Supported Types](supported-types.md) for the full type surface and xlang 
mapping details.
 
@@ -174,7 +174,6 @@ _ = data
   schema and wants faster serialization and smaller size.
 - Register structs with explicit numeric IDs.
 - Disable reference tracking unless the graph requires identity or cycles.
-- Use code generation for hot Go structs when reflection overhead matters.
 - Copy returned bytes only when the data must survive the next serialization 
call.
 
 ## Native And Xlang Comparison
@@ -216,4 +215,3 @@ The default `Fory` instance reuses its buffer. Copy the 
byte slice or use `threa
 - [Type Registration](type-registration.md) - Struct and enum registration
 - [References](references.md) - Shared and circular references
 - [Schema Evolution](schema-evolution.md) - Compatible mode
-- [Code Generation](codegen.md) - Generated serializers
diff --git a/docs/guide/go/thread-safety.md b/docs/guide/go/thread-safety.md
index 19f9209564..c7d746c526 100644
--- a/docs/guide/go/thread-safety.md
+++ b/docs/guide/go/thread-safety.md
@@ -1,6 +1,6 @@
 ---
 title: Thread Safety
-sidebar_position: 12
+sidebar_position: 11
 id: thread_safety
 license: |
   Licensed to the Apache Software Foundation (ASF) under one or more
diff --git a/docs/guide/go/troubleshooting.md b/docs/guide/go/troubleshooting.md
index 2c538385e2..68a8592f8a 100644
--- a/docs/guide/go/troubleshooting.md
+++ b/docs/guide/go/troubleshooting.md
@@ -1,6 +1,6 @@
 ---
 title: Troubleshooting
-sidebar_position: 14
+sidebar_position: 13
 id: troubleshooting
 license: |
   Licensed to the Apache Software Foundation (ASF) under one or more
@@ -129,12 +129,6 @@ type User struct {
 }
 ```
 
-3. **Regenerate codegen** (if using):
-
-```bash
-go generate ./...
-```
-
 ### ErrKindMaxDepthExceeded
 
 **Error**: `max depth exceeded`


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@fory.apache.org
For additional commands, e-mail: commits-h...@fory.apache.org