Script Doc Generator 脚本文档生成器¶
模块简介¶
Script Doc Generator 是 Odin Toolkits For Unity 的核心模块之一，用于一键生成代码的 API 文档（默认生成 Markdown 格式）。该模块支持分析代码中的类、构造函数、方法、属性、事件、字段等成员，并自动整理为结构化文档，同时支持自定义文档生成逻辑。
核心特性¶
- 支持单类型、多类型或整个程序集的文档批量生成
- 自动保留文档中 “## 额外说明” 后的自定义内容（增量生成）
- 支持识别 ChineseSummaryAttribute 特性，提取中文注释作为文档内容
- 生成的文档包含类型介绍、构造方法、非构造方法、事件、属性、字段等完整信息
使用流程¶
打开工具面板¶
通过 Unity 编辑器菜单打开：Tools/Odin Toolkits/Script Doc Generator
设置文档保存路径¶
在工具窗口的 “存放脚本文档的目标文件夹路径” 输入框中，设置文档导出目录
- 支持绝对路径输入
- 支持拖拽文件夹到输入框快速设置
- 若路径不存在，生成时会提示自动创建文件夹
选择类型来源¶
在 “类型来源” 选项中，选择需要生成文档的目标范围
- SingleType：单个类型（如单个类）
- MultipleType：多个类型
- SingleAssembly：整个程序集
选择文档生成器¶
默认提供中文 API 文档生成器（CnAPIDocGeneratorSO），可生成包含中文注释的 Markdown 文档。如需自定义文档格式，可实现 DocGeneratorSO 抽象类并在此处选择自定义生成器。
生成文档¶
点击 “基于解析结果和文档生成器生成 Markdown 文档” 按钮，触发生成流程：
- 若目标类型已标记为 “过时”，会提示确认是否继续
- 若目标路径已存在同名文档，会提示是否覆盖（覆盖时保留 “## 额外说明” 后的内容）
- 生成完成后，自动用默认程序打开文档，并刷新 Unity 资源数据库
中文 API 文档结构¶
文档默认包含以下部分（以中文 API 文档为例）：
- 类型名
- 类型类别（如 class、struct，是否静态 / 抽象）
- 所在程序集、命名空间
- 类型声明代码（如 public class TestClass : MonoBehaviour）
- 注释（来自 ChineseSummaryAttribute）
- 构造方法表格形式展示公共实例构造函数的签名及注释。
- 非构造方法按 “声明的普通方法”“继承的普通方法”“运算符特殊方法” 分类，展示方法签名、注释及声明类。
- 事件按 “声明的事件”“继承的事件” 分类，展示事件名称及注释。
- 属性按 “声明的属性”“继承的属性” 分类，展示属性签名及注释。
- 字段按 “声明的字段”“继承的字段” 分类，展示字段签名及注释。
- 额外说明自动添加工具标识，且保留用户在此部分添加的自定义内容（增量生成时不覆盖）。
高级功能¶
- 支持增量生成
生成文档时，若目标文件已存在，工具会自动保留第一个 “## 额外说明” 之后的内容，仅覆盖前文的 API 信息，在 “额外说明” 部分可以手动补充一些具体案例，或者其他要点。
- 批量生成
选择 “MultipleType” 或 “SingleAssembly” 类型来源时，可一次性为多个类型或整个程序集生成文档，生成数量过多时，会显示进度条。
- 一键同步 XML 的 Summary 注释
工具通过 ChineseSummaryAttribute 特性提取代码成员的中文注释，必须在代码中添加 ChineseSummaryAttribute
[ChineseSummary("这是一个测试类")]
public class TestClass
{
[ChineseSummary("测试字段")]
public int testField;
}
为了减少手动操作，用户在补充完 XML 注释后，可以在 Unity 项目窗口中，右键点击 C# 脚本文件，通过以下菜单快速处理注释：
- Add ChineseSummary：自动为成员添加 ChineseSummaryAttribute
- Remove ChineseSummary：移除脚本中的 ChineseSummaryAttribute
注意事项¶
- 路径不存在时，工具会提示自动创建，若取消则终止生成。
- 生成过时类型的文档时，需手动确认是否继续。
- 自定义文档生成器需继承 DocGeneratorSO 并实现 GetGeneratedDoc 方法。
- 生成的文档编码为 UTF-8，确保兼容性。
常见问题¶
Q：生成的文档缺少某些成员？
A：工具默认只分析公共实例成员，私有成员或非实例成员不会被包含。
Q：如何修改文档格式？
A：可通过自定义 DocGeneratorSO 实现类，重写文档生成逻辑。
Q：“额外说明” 部分的内容被覆盖了？
A：确保自定义内容在 “## 额外说明” 标题之后，工具会保留该标题及之后的内容。
