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.git
The following commit(s) were added to refs/heads/main by this push:
new 6aa22c9b2 docs(compiler): update fory compiler doc (#3183)
6aa22c9b2 is described below
commit 6aa22c9b2043ea704d0d569e7c5e09db94017cb1
Author: Shawn Yang <[email protected]>
AuthorDate: Wed Jan 21 16:31:26 2026 +0800
docs(compiler): update fory compiler doc (#3183)
## Why?
## What does this PR do?
## Related issues
#3099
## Does this PR introduce any user-facing change?
- [ ] Does this PR introduce any public API change?
- [ ] Does this PR introduce any binary protocol compatibility change?
## Benchmark
---
docs/compiler/_category_.json | 4 +-
docs/compiler/compiler-guide.md | 10 ++--
docs/compiler/fdl-syntax.md | 114 ++++++++++++++++++++--------------------
docs/compiler/generated-code.md | 12 ++---
docs/compiler/index.md | 14 ++---
docs/compiler/proto-vs-fdl.md | 24 ++++-----
docs/compiler/type-system.md | 32 +++++------
7 files changed, 106 insertions(+), 104 deletions(-)
diff --git a/docs/compiler/_category_.json b/docs/compiler/_category_.json
index c2cd9e2fe..f835a1000 100644
--- a/docs/compiler/_category_.json
+++ b/docs/compiler/_category_.json
@@ -1,4 +1,6 @@
{
"position": 3,
- "label": "Schema IDL & Compiler"
+ "label": "Schema IDL & Compiler",
+ "collapsible": true,
+ "collapsed": true
}
diff --git a/docs/compiler/compiler-guide.md b/docs/compiler/compiler-guide.md
index 0267a9667..3885a683e 100644
--- a/docs/compiler/compiler-guide.md
+++ b/docs/compiler/compiler-guide.md
@@ -1,7 +1,7 @@
---
-title: FDL Compiler Guide
-sidebar_position: 4
-id: fdl_compiler_guide
+title: Compiler Guide
+sidebar_position: 3
+id: compiler_guide
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
@@ -138,7 +138,7 @@ When compiling FDL files with imports, the compiler
searches for imported files
**Same-directory imports work automatically:**
-```proto
+```protobuf
// main.fdl
import "common.fdl"; // Found if common.fdl is in the same directory
```
@@ -541,7 +541,7 @@ When modifying schemas:
3. **Add new fields** - Use new field numbers
4. **Use `optional`** - For backward compatibility
-```proto
+```protobuf
message User [id=100] {
string id = 1;
string name = 2;
diff --git a/docs/compiler/fdl-syntax.md b/docs/compiler/fdl-syntax.md
index c496b8cfb..0455bb786 100644
--- a/docs/compiler/fdl-syntax.md
+++ b/docs/compiler/fdl-syntax.md
@@ -1,7 +1,7 @@
---
-title: FDL Syntax Reference
+title: Syntax Reference
sidebar_position: 2
-id: fdl_syntax
+id: syntax
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
@@ -29,7 +29,7 @@ An FDL file consists of:
2. Optional import statements
3. Type definitions (enums and messages)
-```proto
+```protobuf
// Optional package declaration
package com.example.models;
@@ -46,7 +46,7 @@ message Order [id=102] { ... }
FDL supports both single-line and block comments:
-```proto
+```protobuf
// This is a single-line comment
/*
@@ -63,7 +63,7 @@ message Example {
The package declaration defines the namespace for all types in the file.
-```proto
+```protobuf
package com.example.models;
```
@@ -90,7 +90,7 @@ Options can be specified at file level to control
language-specific code generat
### Syntax
-```proto
+```protobuf
option option_name = value;
```
@@ -98,7 +98,7 @@ option option_name = value;
Override the Java package for generated code:
-```proto
+```protobuf
package payment;
option java_package = "com.mycorp.payment.v1";
@@ -117,7 +117,7 @@ message Payment {
Specify the Go import path and package name:
-```proto
+```protobuf
package payment;
option go_package = "github.com/mycorp/apis/gen/payment/v1;paymentv1";
@@ -138,7 +138,7 @@ message Payment {
Generate all types as inner classes of a single outer wrapper class:
-```proto
+```protobuf
package payment;
option java_outer_classname = "DescriptorProtos";
@@ -181,7 +181,7 @@ public final class DescriptorProtos {
**Combined with java_package:**
-```proto
+```protobuf
package payment;
option java_package = "com.example.proto";
option java_outer_classname = "PaymentProtos";
@@ -197,7 +197,7 @@ This generates `com/example/proto/PaymentProtos.java` with
all types as inner cl
Control whether types are generated in separate files or as inner classes:
-```proto
+```protobuf
package payment;
option java_outer_classname = "PaymentProtos";
option java_multiple_files = true;
@@ -227,14 +227,14 @@ message Receipt {
**Example without java_multiple_files (default):**
-```proto
+```protobuf
option java_outer_classname = "PaymentProtos";
// Generates: PaymentProtos.java containing Payment and Receipt as inner
classes
```
**Example with java_multiple_files = true:**
-```proto
+```protobuf
option java_outer_classname = "PaymentProtos";
option java_multiple_files = true;
// Generates: Payment.java, Receipt.java (separate files)
@@ -244,7 +244,7 @@ option java_multiple_files = true;
Multiple options can be specified:
-```proto
+```protobuf
package payment;
option java_package = "com.mycorp.payment.v1";
option go_package = "github.com/mycorp/apis/gen/payment/v1;paymentv1";
@@ -259,7 +259,7 @@ message Payment {
FDL supports protobuf-style extension options for Fory-specific configuration:
-```proto
+```protobuf
option (fory).use_record_for_java_message = true;
option (fory).polymorphism = true;
```
@@ -284,7 +284,7 @@ For language-specific packages:
**Example:**
-```proto
+```protobuf
package myapp.models;
option java_package = "com.example.generated";
```
@@ -299,7 +299,7 @@ option java_package = "com.example.generated";
Language-specific options only affect where code is generated, not the type
namespace used for serialization. This ensures cross-language compatibility:
-```proto
+```protobuf
package myapp.models;
option java_package = "com.mycorp.generated";
option go_package = "github.com/mycorp/gen;genmodels";
@@ -321,13 +321,13 @@ Import statements allow you to use types defined in other
FDL files.
### Basic Syntax
-```proto
+```protobuf
import "path/to/file.fdl";
```
### Multiple Imports
-```proto
+```protobuf
import "common/types.fdl";
import "common/enums.fdl";
import "models/address.fdl";
@@ -359,7 +359,7 @@ project/
**common/types.fdl:**
-```proto
+```protobuf
package common;
enum Status [id=100] {
@@ -377,7 +377,7 @@ message Address [id=101] {
**models/user.fdl:**
-```proto
+```protobuf
package models;
import "../common/types.fdl";
@@ -393,7 +393,7 @@ message User [id=200] {
The following protobuf import modifiers are **not supported**:
-```proto
+```protobuf
// NOT SUPPORTED - will produce an error
import public "other.fdl";
import weak "other.fdl";
@@ -418,7 +418,7 @@ Enums define a set of named integer constants.
### Basic Syntax
-```proto
+```protobuf
enum Status {
PENDING = 0;
ACTIVE = 1;
@@ -428,7 +428,7 @@ enum Status {
### With Type ID
-```proto
+```protobuf
enum Status [id=100] {
PENDING = 0;
ACTIVE = 1;
@@ -440,7 +440,7 @@ enum Status [id=100] {
Reserve field numbers or names to prevent reuse:
-```proto
+```protobuf
enum Status {
reserved 2, 15, 9 to 11, 40 to max; // Reserved numbers
reserved "OLD_STATUS", "DEPRECATED"; // Reserved names
@@ -454,7 +454,7 @@ enum Status {
Options can be specified within enums:
-```proto
+```protobuf
enum Status {
option deprecated = true; // Allowed
PENDING = 0;
@@ -470,7 +470,7 @@ enum Status {
When enum values use a protobuf-style prefix (enum name in UPPER_SNAKE_CASE),
the compiler automatically strips the prefix for languages with scoped enums:
-```proto
+```protobuf
// Input with prefix
enum DeviceTier {
DEVICE_TIER_UNKNOWN = 0;
@@ -512,7 +512,7 @@ enum_value := IDENTIFIER '=' INTEGER ';'
**Example with All Features:**
-```proto
+```protobuf
// HTTP status code categories
enum HttpCategory [id=200] {
reserved 10 to 20; // Reserved for future use
@@ -531,7 +531,7 @@ Messages define structured data types with typed fields.
### Basic Syntax
-```proto
+```protobuf
message Person {
string name = 1;
int32 age = 2;
@@ -540,7 +540,7 @@ message Person {
### With Type ID
-```proto
+```protobuf
message Person [id=101] {
string name = 1;
int32 age = 2;
@@ -551,7 +551,7 @@ message Person [id=101] {
Reserve field numbers or names to prevent reuse after removing fields:
-```proto
+```protobuf
message User {
reserved 2, 15, 9 to 11; // Reserved field numbers
reserved "old_field", "temp"; // Reserved field names
@@ -564,7 +564,7 @@ message User {
Options can be specified within messages:
-```proto
+```protobuf
message User {
option deprecated = true;
string id = 1;
@@ -588,7 +588,7 @@ Messages can contain nested message and enum definitions.
This is useful for def
### Nested Messages
-```proto
+```protobuf
message SearchResponse {
message Result {
string url = 1;
@@ -601,7 +601,7 @@ message SearchResponse {
### Nested Enums
-```proto
+```protobuf
message Container {
enum Status {
STATUS_UNKNOWN = 0;
@@ -616,7 +616,7 @@ message Container {
Nested types can be referenced from other messages using qualified names
(Parent.Child):
-```proto
+```protobuf
message SearchResponse {
message Result {
string url = 1;
@@ -635,7 +635,7 @@ message SearchResultCache {
Nesting can be multiple levels deep:
-```proto
+```protobuf
message Outer {
message Middle {
message Inner {
@@ -678,13 +678,13 @@ Fields define the properties of a message.
### Basic Syntax
-```proto
+```protobuf
field_type field_name = field_number;
```
### With Modifiers
-```proto
+```protobuf
optional repeated string tags = 1; // Nullable list
repeated optional string tags = 2; // Elements may be null
ref repeated Node nodes = 3; // Collection tracked as a reference
@@ -708,7 +708,7 @@ Modifiers before `repeated` apply to the field/collection.
Modifiers after
Marks the field as nullable:
-```proto
+```protobuf
message User {
string name = 1; // Required, non-null
optional string email = 2; // Nullable
@@ -729,7 +729,7 @@ message User {
Enables reference tracking for shared/circular references:
-```proto
+```protobuf
message Node {
string value = 1;
ref Node parent = 2; // Can point to shared object
@@ -757,7 +757,7 @@ message Node {
Marks the field as a list/array:
-```proto
+```protobuf
message Document {
repeated string tags = 1;
repeated User authors = 2;
@@ -778,7 +778,7 @@ message Document {
Modifiers can be combined:
-```proto
+```protobuf
message Example {
optional repeated string tags = 1; // Nullable list
repeated optional string aliases = 2; // Elements may be null
@@ -815,7 +815,7 @@ See [Type System](type-system.md) for complete type
mappings.
Reference other messages or enums by name:
-```proto
+```protobuf
enum Status { ... }
message User { ... }
@@ -829,7 +829,7 @@ message Order {
Maps with typed keys and values:
-```proto
+```protobuf
message Config {
map<string, string> properties = 1;
map<string, int32> counts = 2;
@@ -848,7 +848,7 @@ message Config {
Each field must have a unique positive integer identifier:
-```proto
+```protobuf
message Example {
string first = 1;
string second = 2;
@@ -873,7 +873,7 @@ message Example {
Type IDs enable efficient cross-language serialization:
-```proto
+```protobuf
enum Color [id=100] { ... }
message User [id=101] { ... }
message Order [id=102] { ... }
@@ -881,7 +881,7 @@ message Order [id=102] { ... }
### With Type ID (Recommended)
-```proto
+```protobuf
message User [id=101] { ... }
message User [id=101, deprecated=true] { ... } // Multiple options
```
@@ -893,7 +893,7 @@ message User [id=101, deprecated=true] { ... } // Multiple
options
### Without Type ID
-```proto
+```protobuf
message Config { ... }
```
@@ -904,7 +904,7 @@ message Config { ... }
### ID Assignment Strategy
-```proto
+```protobuf
// Enums: 100-199
enum Status [id=100] { ... }
enum Priority [id=101] { ... }
@@ -920,7 +920,7 @@ message OrderItem [id=301] { ... }
## Complete Example
-```proto
+```protobuf
// E-commerce domain model
package com.shop.models;
@@ -1001,7 +1001,7 @@ FDL supports protobuf-style extension options for
Fory-specific configuration. T
### File-Level Fory Options
-```proto
+```protobuf
option (fory).use_record_for_java_message = true;
option (fory).polymorphism = true;
```
@@ -1015,7 +1015,7 @@ option (fory).polymorphism = true;
Options can be specified inside the message body:
-```proto
+```protobuf
message MyMessage {
option (fory).id = 100;
option (fory).evolving = false;
@@ -1036,7 +1036,7 @@ message MyMessage {
### Enum-Level Fory Options
-```proto
+```protobuf
enum Status {
option (fory).id = 101;
option (fory).deprecated = true;
@@ -1054,7 +1054,7 @@ enum Status {
Field options are specified in brackets after the field number:
-```proto
+```protobuf
message Example {
MyType friend = 1 [(fory).ref = true];
string nickname = 2 [(fory).nullable = true];
@@ -1075,7 +1075,7 @@ Field-level options always apply to the field/collection;
use modifiers after
To use `Rc` instead of `Arc` in Rust for a specific field:
-```proto
+```protobuf
message Graph {
ref Node root = 1 [(fory).thread_safe_pointer = false];
}
@@ -1085,7 +1085,7 @@ message Graph {
You can combine standard options with Fory extension options:
-```proto
+```protobuf
message User {
option deprecated = true; // Standard option
option (fory).evolving = false; // Fory extension option
@@ -1099,7 +1099,7 @@ message User {
For reference, the Fory options are defined in `extension/fory_options.proto`:
-```proto
+```protobuf
// File-level options
extend google.protobuf.FileOptions {
optional ForyFileOptions fory = 50001;
diff --git a/docs/compiler/generated-code.md b/docs/compiler/generated-code.md
index 617a3421c..dc414eb47 100644
--- a/docs/compiler/generated-code.md
+++ b/docs/compiler/generated-code.md
@@ -1,7 +1,7 @@
---
-title: Generated Code Reference
+title: Generated Code
sidebar_position: 5
-id: fdl_generated_code
+id: generated_code
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
@@ -25,7 +25,7 @@ This document explains the code generated by the FDL compiler
for each target la
The examples in this document use this FDL schema:
-```proto
+```protobuf
package demo;
enum Status [id=100] {
@@ -56,7 +56,7 @@ When enum values use a protobuf-style prefix (enum name in
UPPER_SNAKE_CASE), th
**Input FDL:**
-```proto
+```protobuf
enum DeviceTier {
DEVICE_TIER_UNKNOWN = 0;
DEVICE_TIER_TIER1 = 1;
@@ -82,7 +82,7 @@ When using nested message and enum definitions, the generated
code varies by lan
**Input FDL:**
-```proto
+```protobuf
message SearchResponse {
message Result {
string url = 1;
@@ -725,7 +725,7 @@ When types don't have explicit type IDs, they use
namespace-based registration:
### FDL
-```proto
+```protobuf
package myapp.models;
message Config { // No @id
diff --git a/docs/compiler/index.md b/docs/compiler/index.md
index be38c9b64..b05dbce13 100644
--- a/docs/compiler/index.md
+++ b/docs/compiler/index.md
@@ -1,7 +1,7 @@
---
-title: FDL Schema Guide
+title: Overview
sidebar_position: 1
-id: schema_index
+id: index
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
@@ -25,7 +25,7 @@ Fory Definition Language (FDL) is a schema definition
language for Apache Fory t
FDL provides a simple, intuitive syntax for defining cross-language data
structures:
-```proto
+```protobuf
package example;
enum Status [id=100] {
@@ -92,7 +92,7 @@ pip install -e .
Create `example.fdl`:
-```proto
+```protobuf
package example;
message Person [id=100] {
@@ -157,13 +157,13 @@ FDL supports two registration modes:
**Numeric Type IDs** - Fast and compact:
-```proto
+```protobuf
message User [id=100] { ... } // Registered with ID 100
```
**Namespace-based** - Flexible and readable:
-```proto
+```protobuf
message Config { ... } // Registered as "package.Config"
```
@@ -173,7 +173,7 @@ message Config { ... } // Registered as "package.Config"
- **`ref`**: Enable reference tracking for shared/circular references
- **`repeated`**: Field is a list/array
-```proto
+```protobuf
message Example {
optional string nullable = 1;
ref Node parent = 2;
diff --git a/docs/compiler/proto-vs-fdl.md b/docs/compiler/proto-vs-fdl.md
index 5b87062dd..8489e77fa 100644
--- a/docs/compiler/proto-vs-fdl.md
+++ b/docs/compiler/proto-vs-fdl.md
@@ -1,7 +1,7 @@
---
-title: Protocol Buffers vs FDL
-sidebar_position: 6
-id: proto_vs_fdl
+title: Protocol Buffers IDL
+sidebar_position: 10
+id: protobuf_idl_support
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
@@ -47,7 +47,7 @@ option go_package = "example.com/models";
**FDL:**
-```proto
+```protobuf
package example.models;
```
@@ -68,7 +68,7 @@ enum Status {
**FDL:**
-```proto
+```protobuf
enum Status [id=100] {
PENDING = 0;
ACTIVE = 1;
@@ -99,7 +99,7 @@ message User {
**FDL:**
-```proto
+```protobuf
message User [id=101] {
string id = 1;
string name = 2;
@@ -131,7 +131,7 @@ message Order {
**FDL:**
-```proto
+```protobuf
message OrderItem [id=200] {
string product_id = 1;
int32 quantity = 2;
@@ -165,7 +165,7 @@ FDL's killer feature is first-class reference tracking:
**FDL:**
-```proto
+```protobuf
message TreeNode [id=300] {
string value = 1;
ref TreeNode parent = 2;
@@ -330,7 +330,7 @@ message Address {
**After (FDL):**
-```proto
+```protobuf
package myapp;
message Address [id=100] {
@@ -360,7 +360,7 @@ message Result {
}
```
-```proto
+```protobuf
// FDL - Use separate optional fields
message Result [id=102] {
optional Success success = 1;
@@ -379,7 +379,7 @@ message Event {
}
```
-```proto
+```protobuf
// FDL
message Event [id=103] {
timestamp created_at = 1;
@@ -390,7 +390,7 @@ message Event [id=103] {
Assign unique type IDs for cross-language compatibility:
-```proto
+```protobuf
// Reserve ranges for different domains
// 100-199: Common types
// 200-299: User domain
diff --git a/docs/compiler/type-system.md b/docs/compiler/type-system.md
index b47a8f05f..141c8d660 100644
--- a/docs/compiler/type-system.md
+++ b/docs/compiler/type-system.md
@@ -1,7 +1,7 @@
---
-title: FDL Type System
-sidebar_position: 3
-id: fdl_type_system
+title: Type System
+sidebar_position: 4
+id: type_system
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
@@ -35,7 +35,7 @@ FDL provides a rich type system designed for cross-language
compatibility:
### Boolean
-```proto
+```protobuf
bool is_active = 1;
```
@@ -69,7 +69,7 @@ FDL provides fixed-width signed integers:
**Examples:**
-```proto
+```protobuf
message Counters {
int8 tiny = 1;
int16 small = 2;
@@ -109,7 +109,7 @@ class Counters:
**Example:**
-```proto
+```protobuf
message Coordinates {
float64 latitude = 1;
float64 longitude = 2;
@@ -121,7 +121,7 @@ message Coordinates {
UTF-8 encoded text:
-```proto
+```protobuf
string name = 1;
```
@@ -137,7 +137,7 @@ string name = 1;
Raw binary data:
-```proto
+```protobuf
bytes data = 1;
```
@@ -155,7 +155,7 @@ bytes data = 1;
Calendar date without time:
-```proto
+```protobuf
date birth_date = 1;
```
@@ -171,7 +171,7 @@ date birth_date = 1;
Date and time with nanosecond precision:
-```proto
+```protobuf
timestamp created_at = 1;
```
@@ -187,7 +187,7 @@ timestamp created_at = 1;
Enums define named integer constants:
-```proto
+```protobuf
enum Priority [id=100] {
LOW = 0;
MEDIUM = 1;
@@ -270,7 +270,7 @@ FORY_ENUM(Priority, LOW, MEDIUM, HIGH, CRITICAL);
Messages are structured types composed of fields:
-```proto
+```protobuf
message User [id=101] {
string id = 1;
string name = 2;
@@ -294,7 +294,7 @@ message User [id=101] {
The `repeated` modifier creates a list:
-```proto
+```protobuf
repeated string tags = 1;
repeated User users = 2;
```
@@ -322,7 +322,7 @@ repeated User users = 2;
Maps with typed keys and values:
-```proto
+```protobuf
map<string, int32> counts = 1;
map<string, User> users = 2;
```
@@ -348,7 +348,7 @@ Avoid using messages or complex types as keys.
The `optional` modifier makes a field nullable:
-```proto
+```protobuf
message Profile {
string name = 1; // Required
optional string bio = 2; // Nullable
@@ -376,7 +376,7 @@ message Profile {
The `ref` modifier enables reference tracking:
-```proto
+```protobuf
message TreeNode {
string value = 1;
ref TreeNode parent = 2;
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
