mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-03-24 20:34:29 +08:00
a021941cab
- 创建 DOCUMENTATION_STANDARDS.md 文件定义 Markdown 语法规范 - 添加泛型标记转义规则和 HTML 标签转义说明 - 提供内部链接验证规则和已存在文档路径列表 - 定义代码块规范和 Frontmatter 规范 - 添加文档结构规范和验证清单 - 配置 .claude/settings.json 启用 oh-my-claudecode 插件
206 lines
5.3 KiB
Markdown
206 lines
5.3 KiB
Markdown
# GFramework 文档编写规范
|
||
|
||
## Markdown 语法规范
|
||
|
||
### 1. 泛型标记转义
|
||
|
||
在 Markdown 文档中,所有泛型标记必须转义,否则会被 VitePress 误认为 HTML 标签。
|
||
|
||
**错误示例**:
|
||
```markdown
|
||
`Option<T>` 是一个泛型类型
|
||
`Result<TValue, TError>` 表示结果
|
||
public class Repository<TData> { }
|
||
```
|
||
|
||
**正确示例**:
|
||
```markdown
|
||
`Option<T>` 是一个泛型类型
|
||
`Result<TValue, TError>` 表示结果
|
||
public class Repository<TData> { }
|
||
```
|
||
|
||
**常见泛型标记**:
|
||
- `<T>` → `<T>`
|
||
- `<TResult>` → `<TResult>`
|
||
- `<TValue>` → `<TValue>`
|
||
- `<TError>` → `<TError>`
|
||
- `<TSaveData>` → `<TSaveData>`
|
||
- `<TData>` → `<TData>`
|
||
- `<TNode>` → `<TNode>`
|
||
|
||
### 2. HTML 标签转义
|
||
|
||
如果需要在文档中显示 HTML 标签,必须转义:
|
||
- `<summary>` → `<summary>`
|
||
- `<param>` → `<param>`
|
||
- `<returns>` → `<returns>`
|
||
|
||
### 3. 链接验证
|
||
|
||
**内部链接规则**:
|
||
- 使用相对路径: `/zh-CN/core/events`
|
||
- 确保目标文件存在
|
||
- 不要链接到尚未创建的页面
|
||
|
||
**已存在的文档路径**:
|
||
|
||
**Core 模块**:
|
||
- `/zh-CN/core/architecture` - 架构系统
|
||
- `/zh-CN/core/ioc` - IoC 容器
|
||
- `/zh-CN/core/events` - 事件系统
|
||
- `/zh-CN/core/command` - 命令系统
|
||
- `/zh-CN/core/query` - 查询系统
|
||
- `/zh-CN/core/model` - Model 系统
|
||
- `/zh-CN/core/system` - System 系统
|
||
- `/zh-CN/core/utility` - Utility 系统
|
||
- `/zh-CN/core/controller` - Controller 系统
|
||
- `/zh-CN/core/logging` - 日志系统
|
||
- `/zh-CN/core/pool` - 对象池
|
||
- `/zh-CN/core/property` - 可绑定属性
|
||
- `/zh-CN/core/lifecycle` - 生命周期管理
|
||
- `/zh-CN/core/coroutine` - 协程系统
|
||
- `/zh-CN/core/resource` - 资源管理
|
||
- `/zh-CN/core/state-machine` - 状态机
|
||
- `/zh-CN/core/cqrs` - CQRS 与 Mediator
|
||
- `/zh-CN/core/functional` - 函数式编程
|
||
- `/zh-CN/core/pause` - 暂停管理
|
||
- `/zh-CN/core/configuration` - 配置管理
|
||
- `/zh-CN/core/ecs` - ECS 系统集成
|
||
- `/zh-CN/core/extensions` - 扩展方法
|
||
- `/zh-CN/core/rule` - 规则系统
|
||
- `/zh-CN/core/environment` - 环境系统
|
||
- `/zh-CN/core/context` - 上下文系统
|
||
- `/zh-CN/core/async-initialization` - 异步初始化
|
||
|
||
**Game 模块**:
|
||
- `/zh-CN/game/scene` - 场景系统
|
||
- `/zh-CN/game/ui` - UI 系统
|
||
- `/zh-CN/game/data` - 数据与存档
|
||
- `/zh-CN/game/storage` - 存储系统
|
||
- `/zh-CN/game/serialization` - 序列化系统
|
||
- `/zh-CN/game/setting` - 设置系统
|
||
|
||
**Godot 模块**:
|
||
- `/zh-CN/godot/architecture` - Godot 架构集成
|
||
- `/zh-CN/godot/scene` - Godot 场景系统
|
||
- `/zh-CN/godot/ui` - Godot UI 系统
|
||
- `/zh-CN/godot/pool` - Godot 节点池
|
||
- `/zh-CN/godot/resource` - Godot 资源仓储
|
||
- `/zh-CN/godot/logging` - Godot 日志系统
|
||
- `/zh-CN/godot/pause` - Godot 暂停处理
|
||
- `/zh-CN/godot/extensions` - Godot 扩展
|
||
- `/zh-CN/godot/coroutine` - Godot 协程
|
||
- `/zh-CN/godot/signal` - Godot 信号
|
||
- `/zh-CN/godot/storage` - Godot 存储
|
||
|
||
**教程**:
|
||
- `/zh-CN/tutorials/coroutine-tutorial` - 协程系统教程
|
||
- `/zh-CN/tutorials/state-machine-tutorial` - 状态机教程
|
||
- `/zh-CN/tutorials/resource-management` - 资源管理教程
|
||
- `/zh-CN/tutorials/save-system` - 存档系统教程
|
||
- `/zh-CN/tutorials/godot-complete-project` - Godot 完整项目
|
||
- `/zh-CN/tutorials/functional-programming` - 函数式编程实践
|
||
- `/zh-CN/tutorials/pause-system` - 暂停系统实现
|
||
- `/zh-CN/tutorials/data-migration` - 数据迁移实践
|
||
- `/zh-CN/tutorials/godot-integration` - Godot 集成
|
||
- `/zh-CN/tutorials/advanced-patterns` - 高级模式
|
||
|
||
**其他**:
|
||
- `/zh-CN/getting-started/quick-start` - 快速开始
|
||
- `/zh-CN/getting-started/installation` - 安装指南
|
||
- `/zh-CN/best-practices/architecture-patterns` - 架构模式
|
||
|
||
**不存在的路径** (不要链接):
|
||
- `/zh-CN/best-practices/performance` - 尚未创建
|
||
- `/zh-CN/core/serializer` - 错误路径,应使用 `/zh-CN/game/serialization`
|
||
|
||
## 代码块规范
|
||
|
||
### 1. 代码块语言标识
|
||
|
||
始终指定代码块的语言:
|
||
|
||
```markdown
|
||
\`\`\`csharp
|
||
public class Example { }
|
||
\`\`\`
|
||
|
||
\`\`\`bash
|
||
npm install
|
||
\`\`\`
|
||
```
|
||
|
||
### 2. 代码注释
|
||
|
||
代码示例应包含中文注释:
|
||
|
||
```csharp
|
||
// 创建玩家实体
|
||
var player = new Player
|
||
{
|
||
Name = "玩家1", // 玩家名称
|
||
Level = 1 // 初始等级
|
||
};
|
||
```
|
||
|
||
## Frontmatter 规范
|
||
|
||
每个文档必须包含正确的 frontmatter:
|
||
|
||
```yaml
|
||
---
|
||
title: 文档标题
|
||
description: 简短描述（1-2 句话）
|
||
---
|
||
```
|
||
|
||
## 文档结构规范
|
||
|
||
### 指南文档结构
|
||
|
||
1. 概述
|
||
2. 核心概念
|
||
3. 基本用法
|
||
4. 高级用法
|
||
5. 最佳实践
|
||
6. 常见问题
|
||
7. 相关文档
|
||
|
||
### 教程文档结构
|
||
|
||
1. 学习目标
|
||
2. 前置条件
|
||
3. 步骤 1-N (3-7 步)
|
||
4. 完整代码
|
||
5. 运行结果
|
||
6. 下一步
|
||
7. 相关文档
|
||
|
||
## 验证清单
|
||
|
||
生成文档后,必须检查:
|
||
|
||
- [ ] 所有泛型标记已转义 (`<T>` → `<T>`)
|
||
- [ ] 所有内部链接指向存在的页面
|
||
- [ ] Frontmatter 格式正确
|
||
- [ ] 代码块指定了语言
|
||
- [ ] 代码包含中文注释
|
||
- [ ] 文档结构完整
|
||
- [ ] 没有 HTML 标签错误
|
||
|
||
## 自动修复脚本
|
||
|
||
如果文档已生成,可以使用以下脚本修复常见问题:
|
||
|
||
```bash
|
||
# 修复泛型标记
|
||
sed -i 's/<T>/\<T\>/g' file.md
|
||
sed -i 's/<TResult>/\<TResult\>/g' file.md
|
||
sed -i 's/<TValue>/\<TValue\>/g' file.md
|
||
sed -i 's/<TError>/\<TError\>/g' file.md
|
||
|
||
# 验证构建
|
||
cd docs && bun run build
|
||
```
|