RFC-0055：文档注释

摘要

记录 FIDL。

与其他 RFC 的关系

此 RFC 已通过以下修订：

• RFC-0043：文档注释格式

设计初衷

良好的文档不仅是扩大团队的重要组成部分，也是定义稳定 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 应失败。

其他工具

应将一个名为 fidldoc 的标准工具添加到 tools 目录中。Fidldoc 在使用 FIDL JSON IR 后会生成 Markdown。Markdown 是我们目前在其他一流语言的文档工具中使用的格式。

其他

Wire 格式不受这些更改的影响。语言绑定选择如何显示 docstring（或是否显示）是各自社区的实现细节，或者可能作为额外的 FTP。

应修改样式指南，以便优先使用 /// 而非 doc 属性，但其他方面不作更改。

文档和示例

三重注释是一种比较常见的文档注释标记方式，不应成为理解 fidl 语言的重大障碍。应在现有文档中添加使用三重注释的示例，并说明如何使用属性注解。

用户使用此功能的主要方式是通过生成的输出。

向后兼容性：此功能已与所有近期之前的 fidlc 编译器向后兼容。虽然三重注释语法糖不会提供新功能，但不会破坏早期编译器。

文档属性注释无需任何语言更改即可正常使用。

性能

除了 JSON IR 大小略有增加外，预计不会有任何性能变化。我们还会在编译时生成文档，这会略微减慢构建速度。

安全

不适用

测试

不适用

缺点、替代方案和未知情况

采用该方法需要对方法和使用的具体语法达成一般共识。语法易于修改（和自行车测试），并且会改变提案的核心思想。

关于 fidldoc 的潜在替代方案是，编译器自行生成文档。您可能还需要使用现有的后端生成器方法来实现此目的。生成的文档的输出格式也可以讨论。

另一种方法是将文档注释表示为 AST 中的一等公民。虽然此策略没有任何真正的缺点，但您会失去将其建模为属性的一些可扩展性优势。将来，我们可能需要为文档工具添加更多信息，而属性样式使我们能够在不破坏更改的情况下实现这一点。例如，我们可能希望允许指定评论的 Markdown 语言。这样，系统便会在同一输出（属性）中保留用于生成文档的所有信息。它还会强制执行良好的规则，即具有类似放置约束条件的文档注释和属性会以相同的方式解析。

在先技术和参考文档

大多数语言都有文档工具。这借鉴了 dartdoc、rustdoc 和 javadoc 的先前做法（主要是在“不该怎么做”方面）