RFC-0055：文档注释

摘要

记录 FIDL。

与其他 RFC 的关系

此 RFC 已由以下 RFC 修正：

• RFC-0043：文档注释格式

设计初衷

良好的文档不仅是团队扩展的重要组成部分，记录 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 应失败。

其他工具

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

其他

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

应修改样式指南，使其优先使用 /// 而不是 doc 属性，但除此之外，其他内容保持不变。

文档和示例

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

用户主要通过生成的输出内容来使用此功能。

向后兼容性此功能已向后兼容所有近期之前的 fidlc 编译器。虽然三斜线注释语法糖不会有新功能，但它们不会破坏旧版编译器。

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

性能

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

安全

不适用

测试

不适用

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

必须就方法和所用特定语法达成一般性共识，才能采用该方法。该语法的修改非常简单（并且可以进行 bikeshedding），但确实会改变提案的核心思想。

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

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

在先技术和参考资料

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