# NewLife 模块文档标准模板 本文件定义每个功能模块文档的标准结构。所有 `Doc/*.md` 文件应遵循本模板，确保格式统一、机器可解析、人类可读。 --- ## 模板结构 ```markdown --- title: "{中文名}" namespace: "{命名空间}" project: "{NuGet包名}" url: "https://newlifex.com/core/{slug}" updated: "{YYYY-MM-DD}" --- # {中文名} {一段话概述：这是什么、解决什么问题、核心优势} ## 核心概念 {模块的关键设计理念，2-5 个要点} ## 快速开始 ### 安装 ```shell dotnet add package {NuGet包名} ``` ### 基础用法 ```csharp // 最简化的可运行示例 ``` ## API 参考 ### {核心类/接口名} {一句话描述} ```csharp // 关键公共成员签名（从源码提取，不虚构） public interface IXxx { /// <summary>说明</summary> ReturnType Method(ParamType param); } ``` ### {其它核心类} ... ## 常见场景 ### 场景 1：{动词短语} {场景描述} ```csharp // 完整可运行代码 ``` ### 场景 2：{动词短语} ... ## 高级用法 {扩展点、自定义实现、配置选项等} ## 注意事项 - {注意点 1} - {注意点 2} ## 与其它模块的关系 | 相关模块 | 关系 | |---------|------| | {模块名} | {如何配合使用} | ## 更新历史 | 版本 | 变更 | |------|------| | {版本号} | {变更说明} | ``` --- ## 格式规范 ### YAML Frontmatter | 字段 | 必选 | 说明 | |------|------|------| | `title` | ✅ | 文档标题（中文，如"统一缓存接口ICache"） | | `namespace` | ✅ | .NET 命名空间 | | `project` | ✅ | NuGet 包名 | | `url` | ❌ | 官网对应页面 URL | | `updated` | ✅ | 最后更新日期 | ### 代码示例要求 1. **来自源码**：API 签名必须从实际源码提取，不虚构方法名或参数 2. **可运行**：示例代码应可直接复制使用，包含必要 using 3. **NewLife 风格**：使用 `String`/`Int32` 而非 `string`/`int` 4. **简洁**：快速开始用最少代码展示核心功能，完整示例放常见场景 ### 篇幅控制 | 文档类型 | 建议行数 | 说明 | |---------|---------|------| | 核心接口（ICache, ILog 等） | 200-400 行 | 详细覆盖 | | 实现类（MemoryCache 等） | 100-200 行 | 重点差异和扩展 | | 工具类（SecurityHelper 等） | 100-150 行 | API 列表 + 示例 | | 内部组件（Codec 等） | 50-100 行 | 简要说明 | ### 文件命名 格式：`{中文名}{英文名}.md` ``` 缓存系统ICache.md 网络服务端NetServer.md 安全扩展SecurityHelper.md 高级定时器TimerX.md ``` --- ## 已有文档格式统一检查清单 对已有 Doc/*.md 文件，逐步补充以下内容： - [ ] 添加 YAML frontmatter（title/namespace/project/updated） - [ ] 确保有"快速开始"段落 - [ ] 确保 API 签名与当前源码一致 - [ ] 代码示例使用 NewLife 规范（String/Int32） - [ ] 注明与其它模块的关联关系 --- （完）