用途:在 Biome 中编写或修改 Rust 注释时,先判断注释的读者与最终去向,再决定写法。Rust 语法本身不决定注释受众,/// 或 pub 也不代表读者身份,需要顺着传播路径检查附近的 derive、属性、宏、生成器和帮助快照。
读者识别:普通实现 //、内部条目 rustdoc 和多数模块文档面向贡献者;派生 JsonSchema 的配置类型上的 rustdoc 面向读 JSON Schema 的用户;被 Bpaf 消费的 rustdoc 面向 CLI 帮助读者;面向守护进程的 Workspace 方法及其序列化类型面向守护进程客户端作者;declare_lint_rule! 或 declare_source_rule! 内的 rustdoc 面向网站上的规则或辅助文档用户。一个文件可以混合多种受众,注释也可能服务多个去向,应按最普通的读者来写,只用所有去向都支持的格式,并检查渲染结果。
贡献者文档:为懂 Rust 但看不到对话、PR、issue 或 diff 的贡献者写,描述当前代码,不叙述变更历史,不面向审稿人辩解。
最终用户文档:面向可能首次使用该功能的成年人,不要求懂 Rust、Biome 内部或目标语言的高级术语。使用 ELI18 风格:对初学者友好、技术完整、不幼稚。遵循 Biome 理念:减少行话、定义必要术语、明确默认值、前提、效果、限制、回退与错误恢复;使用公开名称如 files.includes、--write、openFile,不要泄漏 Rust 标识符。
注释类型://! 模块文档解释模块存在的原因、核心概念、各部分关系与持久设计理由;/// 条目文档描述该条目的实际受众契约;// 行内注释解释约束、变通、非显然耦合或为何显而易见实现是错的。贡献者能从名称、类型和控制流推断的内容应删除;最终用户可能只看到帮助条目、悬停、生成的 API 或规则页,应保留自包含的行为摘要。
禁用模式:不要叙述下一行代码、不要叙述变更历史、不要写给审稿人的辩解、不要重复条目名称、不要在用户文档中写实现语言、不要模糊措辞、不要临时分节横幅。长文件可用配对 // #region 与 // #endregion 做折叠导航,但名称不能替代条目 rustdoc。
编辑现有代码:改源注释而非生成产物;行为变化时精确更正文字而非换成泛泛描述;保持改动聚焦。完成前应只读 diff 中的注释,识别读者与每个去向,确保无需对话、历史、审稿人、issue 或 diff 即可理解,检查公开名称、示例、术语与语法,必要时应检查生成或渲染输出。
限制:资料未提供具体安装命令、收费或平台信息。