RFC-0055：文档注释

摘要

为 FIDL 编写文档。

与其他 RFC 的关系

此 RFC 已被以下 RFC 修正：

• RFC-0043：文档注释格式

设计初衷

良好的文档不仅是团队扩容的重要组成部分，为我们的 API 编写文档也是定义稳定 API 的重要组成部分。Fuchsia API 主要在 FIDL 中实现，大量文档都保留在注释中，难以显示。更糟糕的是，人们经常查看生成的绑定，以了解如何使用接口。此提案是针对 FIDL 语言及其接口的全面文档策略的第一步。

设计

我们提出了两项 FIDL 源语言变更。一项是标准 Doc 属性，另一项是语法糖，旨在提高编写文档的人体工程学。

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 的标准工具添加到工具目录中。Fidldoc 在使用 FIDL JSON IR 后会生成 Markdown。Markdown 是我们目前与其他一流语言的文档工具一起使用的格式。

其他

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

样式指南应进行修改，以优先使用 /// 而不是文档属性，但其他方面保持不变。

文档和示例

三斜杠注释是一种相对常见的表示文档注释的方式 不应成为理解 fidl 语言的障碍。应将使用三斜杠注释的示例添加到现有文档中，并解释如何使用属性注释。

人们使用此功能的主要方式是在生成的输出中。

向后兼容性此功能已向后兼容所有最近的先前 fidlc 编译器。虽然三斜杠注释语法糖没有新功能，但它们不会破坏较早的编译器。

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

性能

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

安全

不适用

测试

不适用

缺点、替代方案和未知因素

采用此方法和所用特定语法需要达成普遍共识。语法很容易修改（和进行自行车棚讨论），并且不会改变提案的核心思想。

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

另一种替代方案是将文档注释表示为 AST 中的一流公民。虽然此策略没有任何真正的缺点，但您会失去将其建模为属性的一些可扩展性优势。将来，我们可能希望为文档工具添加其他信息，而属性样式可以在不进行重大更改的情况下实现这一点。例如，我们可能希望允许指定注释的 Markdown 语言。这样一来，生成文档的所有信息都将保留在同一输出（属性）中。它还强制执行良好的规律性，即以相同的方式解析具有类似放置约束的文档注释和属性。

在先技术和参考文档

大多数语言都有文档工具。这借鉴了 dartdoc、rustdoc 和 javadoc 的在先技术（主要是不要做什么）