| RFC-0055：文档注释 | |
|---|---|
| 状态 | 已接受 |
| 领域 |
|
| 说明 | 记录 FIDL。 |
| 作者 | |
| 提交日期（年-月-日） | 2018-07-31 |
| 审核日期（年-月-日） | 2018-08-20 |
摘要
记录 FIDL。
与其他 RFC 的关系
此 RFC 已由以下人员修改：
设计初衷
好的文档不仅是扩大团队规模的重要组成部分， 我们的 API 是定义稳定 API 的重要一环。Fuchsia API 是 主要使用 FIDL 实现，但有大量文档需要留待 。更糟糕的是， 看看生成的绑定，了解如何使用接口这个 提案是制定综合性文档策略的第一步， FIDL 语言及其接口。
设计
我们提议对 FIDL 源语言进行两项更改。标准 Doc 属性
和句法糖，以改进撰写文档的工效学设计。
文档属性
任意属性是 FIDL 语言中受支持的组成部分。
对 Doc 属性进行标准化适用于生成
格式的文档。使用属性作为文档的基础
工具还允许将其他选项添加到格式化输出
而无需进行破坏性更改
[Discoverable, Doc = "Primary Bluetooth control service to access bluetooth"]
interface Control {
...
[Doc = "Sets the public Bluetooth |name| for this device"]
10: SetName(string? name) -> (fuchsia.bluetooth.Status status);
}
目前，每个语言元素只能有一个 Doc 属性。这个
所以所有文本都必须用大括号括起来，
内容过长。
句式糖
为了解决使用属性导致的糟糕人体工学问题，需要添加一层语法糖 。
这涉及对 FIDL 语言规范进行细微更改。评论为 当前在 FIDL 词法运算期间被忽略。此 FTP 不支持添加 只能向 AST 发送常规注释，只能发送文档注释。
属性是 FIDL 语言用来表达 附加至结构的元数据。将文档注释视为一种特殊行为 这样做可以简化 IR 中元数据的使用。
我们建议的语法修改显示在 FTP 的附录部分，但 主要涉及添加其他规则以及次要规则重新排序。
documentation-comment = "///", STRING-LITERAL, "\n"
interface Control {
/// Sent when an adapter with the given |identifier| has been
/// removed from the system.
10102: -> OnAdapterRemoved(string identifier);
}
这样做可以脱糖：
[Doc="Sent when an adapter with the given |identifier| has been\n removed from the system\n"]
文档注释内容
文档评论主要是自由格式文本。支持任意特定格式 提供给作者、团队或未来的风格指南。唯一添加的原语是 标识符标记，目前提议采用竖线 (|) 的形式，将本地 标识符。非限定标识符的范围限定为对象下的成员 该属性也会附加。完全限定标识符 （例如：|fuchsia.bluetooth.ErrorCode|）引用当前外部的对象 范围。
最后，如果存在任何 缺少标识符，但该属性仍会包含并传递 语言绑定这将防止文档损坏。将 标识符发送到 IR 或在解析步骤中有意避免 因此需要非常复杂提取属于 文档工具 (fidldoc)。文档生成应添加为 标准调试 build 的必要部分，如果出现以下情况，则整个 build 应该会失败： 文档未成功生成。
其他工具
应将一个名为 fidldoc 的标准工具添加到 tools 目录中。Fidldoc 将在使用 FIDL JSON IR 后生成 Markdown。Markdown 它与另一种一流语言的文档所用的格式相同， 工具。
其他
这些更改不会影响 Wire 格式。语言绑定选择 实现细节 或者作为其他 FTP 上传。
应修改样式指南，使 /// 优先于 doc 属性，但
则保持现状。
文档和示例
三重注释是表示文档注释的一种相对常见方式 不应该成为理解保真语言的一大障碍示例 都应该添加到现有文档中 如何使用属性注释。
用户使用此功能的主要方式是在生成的 输出。
向后兼容性 此功能已向后兼容 最新的 Fillc 编译器。虽然 三注释语法糖，因此不会破坏之前的编译器。
文档属性评论无需更改语言即可生效。
性能
除了 JSON IR 小幅增加之外，性能预计不会发生任何变化 。我们还会在编译时生成文档，这会降低 进行小幅构建
安全
不适用
测试
不适用
缺点、替代方案和未知问题
必须就方法和所用的特定语法达成共识 采用率。该语法很容易修改（并会被自行车删除）， 提案的核心理念
就 fidldoc 而言，可能的替代方案是让编译器生成 文档本身。如果使用现有的后端 生成器方法。所生成文档的输出格式可能 也可以参与讨论
另一种替代方案是将文档注释表示为一等 AST 的公民。虽然这种策略并没有什么实际的缺点 会失去将模型作为属性建模的一些可扩展性优势。将来某天 我们可能需要为文档工具和 属性样式可在不破坏性更改的情况下实现这一点。例如，我们 可能希望允许指定评论的 Markdown 语言。这会 然后将生成文档所需的全部信息 相同的输出（属性）。它还能够让文档 具有相似展示位置限制的注释和属性会在 。
先验技术和参考资料
大多数语言都有文档工具。这借鉴了 Dartdoc 的先验技术， rustdoc 和 javadoc（主要是在不应该执行的操作中）