| 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|）来引用当前范围之外的对象。
最终，如果缺少任何标识符，fidldoc 文档生成应该会失败，但该属性仍将包含在内，并传入语言绑定中。这样可以防止文档损坏。由于这些步骤较为复杂，应有意避免将标识符添加到 IR 或解析步骤中。标识符提取方法由文档工具 (fidldoc) 负责。文档生成应作为标准调试 build 的必要部分添加；如果未成功生成文档，整个 build 应该会失败。
其他工具
应在 tools 目录中添加一个名为 fidldoc 的标准工具。Fidldoc 会在使用 FIDL JSON IR 后生成 Markdown。Markdown 是我们在 其他一级语言的文档工具中使用的当前格式。
其他
有线格式不受这些更改的影响。语言绑定选择如何呈现文档字符串，或者如果它们显示文档字符串，将留作其各自社区的实现细节，也可能是其他 FTP。
应将样式指南修改为优先使用 /// 而不是 doc 属性，但其他情况则保持不变。
文档和示例
三条注释是一种相对常见的文档注释表示方式，应该不会成为理解 fidl 语言的一大障碍。使用三重注释的示例应添加到现有文档中，并说明如何使用属性注释。
人们使用此功能的主要方式是在生成的输出中。
向后兼容性：此功能已经向后兼容所有最新的 fidlc 编译器。虽然对于三重注释语法糖而言，新功能不存在，但它们不会破坏之前的编译器。
使用文档属性注释时，无需更改任何语言。
性能
除了 JSON IR 大小略有增加之外，预计不会发生性能变化。我们还将在编译时生成文档，这会略微减慢构建速度。
安全性
不适用
测试
不适用
缺点、替代方案和未知情况
只有在获得对方法和使用的具体语法的一致意见才能采用。语法易于修改（和自行车移除），并且确实改变了提案的核心理念。
关于 fidldoc，可能的替代方案是编译器自行生成文档。您也可以使用现有的后端生成器方法来执行此操作。也可以讨论所生成文档的输出格式。
另一种方法是在 AST 中将文档注释表示为一等公民。虽然此策略没有真正的缺点，但您会失去将其建模为属性的某些可扩展优势。有一天，我们可能希望为文档工具添加额外的信息，而属性样式可以在不破坏性更改的情况下做到这一点。例如，我们可能希望允许指定评论的 Markdown 语言。这样，您就可以在同一输出（属性）中保留用于生成文档的所有信息。它还具有一种很好的规律性，以相同的方式解析具有类似放置限制的文档注释和属性。
早期技术和参考资料
大多数语言都提供文档工具。这借鉴了 dartdoc、rustdoc 和 javadoc 的先前技术（主要是错误做法）