RFC-0043：文档注释格式

RFC-0043：文档注释格式
状态	已接受
领域	FIDL
说明	此 FTP 将用于编写文档注释的单一格式标准化。这种格式可供以其他人类可读和机器消费格式（例如HTML、Markdown）。
作者	jeremymanson@google.com
提交日期（年-月-日）	2019-05-06
审核日期（年-月-日）	2019-05-30

摘要

此 RFC 将用于编写文档的单一格式标准化 评论。 此格式可供在 Google Cloud 中 其他人类可读和机器可使用的格式（例如，HTML、Markdown）。

设计初衷

我们目前有一份 API 文档评分准则，其中非常明确地说明了 需要记录 FIDL 代码的哪些方面，包括参数、 返回值和错误。 我们也鼓励开发者提供 API 用法示例。 但是，我们没有为开发者提供明确的表达方式 功能。

随着 fidldoc 工具的出现，提供 一种在注释中表达格式的方法。 例如，编写评论的开发者应该知道如何设置列表格式 。 它们还必须知道如何指明某些内容是返回值或 参数，以便在输出中正确呈现。

设计

TL;DR：我们希望对评论使用 Markdown。 当然，细节在于细节。

此 RFC 对 API 文档评分准则以及我们使用的工具进行了修改 处理 FIDL API 文档。 这不影响 FIDL 的措辞，因为一系列合法的 FIDL 保持不变

为什么选择 Markdown？

文档注释的解决方案空间可分为两部分： “开发我们自己的解决方案”和“使用现有解决方案” 我们认为 FIDL 是一个不够大的生态系统， 为注释语法制定了单独的标准。 通过使用现有解决方案，开发者将能够利用 外部文档和工具（可能还包括他们现有的 知识）。 此外，通过使用现有解决方案，我们还可以节省开发时间。

如果我们承诺使用现有解决方案，则必须选择一个。 有几种针对特定语言的解决方案可以进行扩展 （例如 javadoc 和 python 文档字符串）。 还有通用解决方案（例如LaTeX、RST、Markdown）。

我们认为 Markdown 是最佳选择。 与针对特定语言的解决方案不同，有许多工具 允许 Markdown 集成到新语言。 Markdown 也被开发者广泛使用和理解：它用于 提供示例，由 GitHub 提供。 最后，还有许多语言（例如，Rust 和 Kotlin）正在实现标准化 Markdown 的语法，并且开始取代现有的 其他语言的解决方案（例如，LLVM 将成为 从 RST 迁移到 Markdown）。

Markdown，是什么意思？

Markdown 有多种实现方式， 行为 数量不限都是合理的选择。 我们选择 CommonMark，因为它是最接近标准的方法。 适用于其工具需要同时针对 CommonMark 和 Markdown 实现，我们建议确保他们的文档与 我们都会尽可能地做到这一点

Markdown 没有可扩展性，因此不能帮助您表达 元素。 我们添加了特殊用途的 Markdown 扩展， fidldoc（以及其他 API 文档使用工具）。

文档注释采用 Markdown 编写，且位于其所属的元素之前 文档。 其中包含一段说明，后接文档（可选） 参数、错误和“查看”（这表示读者应查看 查看所引用的 API）。

参数和错误

应记录请求参数：

* request `paramname` Description of parameter

应记录响应参数：

* response `paramname` Description of parameter

我们还将 param 和 return（或 in 和 out）作为 关键字，而不是 request 和 response。

在方法使用与参数不同的标识符的情况下 对于请求和响应，request 和 response 均为 可选属性。

返回时不含参数值 (Foo() -> ()) 的方法可以使用 字词 response，没有对应的文档参数。

错误子句应记录在文档中：

* error Description of error values

完全限定名称

完全限定名称采用以下格式：

<library>/<top level declaration>.<member>

这可以唯一标识任何成员，因为没有过载。

目前，序号哈希基于以下形式的名称：<library>.<top level declaration>/<member>（请参阅 RFC-0020）和 fidlc 使用 <library>.<top level declaration>/<member> 格式报告错误。 我们打算按照上述明确格式设置这些内容。 我们将修改 RFC-0029: Increasing Method Ordinals 以使用 将 <library>/<top level declaration>.<member> 作为名称进行哈希处理，然后修改 fidlc 持续报告错误。

指向其他 FIDL 语言元素（具有相关文档）的链接 （或记录的实体），可以通过添加 [`link-target`] 来创建。 例如，[`fidl.io/NodeInfo`] 会链接到相应库的文档。 解析规则如下：

1. 首先，检查嵌套元素。 如果您要记录struct Object，并且其中包含一位成员 event，您可以将其称为 [`event`]。
2. 接下来，与记录的元素处于同一作用域级别的元素将 。 例如，如果您要记录协议方法 foo()，而 同一协议中包含 bar() 方法，您可以将其称为 [`bar`]。
3. 接下来，检查封闭范围的元素 范围。 例如，如果您要记录协议方法 foo()，并且 同一个库中还有另一个名为 Info 的协议，您可以参考 向其（及其元素）添加 [`Info`]。
4. 3 在连续封闭的作用域中重复，直到您位于顶层 级别范围。 如果您记录的是协议方法 foo()，并且编写了 [`fuchsia.io/NodeInfo`]，它将引用并集 fuchsia.io/NodeInfo。

完全限定名称的格式为 <library>/<top level declaration>.<member>，请参阅上文的详细信息。

对于其他链接快捷方式，您可以指定链接目标，例如：

[fuchsia-concepts]: https://fuchsia.dev/fuchsia-src/concepts

该行不会显示在工具输出中。

如果工具在运行时已知给定 FIDL 目标类型， 无需指定位置。 例如，有关 fuchsia.sys/ComponentController 的文档 和 fuchsia.sys/EnvironmentController 将在 同一工具调用。 该工具将识别这些元素之间的联系。

开发者还可以使用以下内容来表示存在相关 API：

* see [`fidl.io`]

视情况而定。

实施策略

实施工作包括将此纳入 FIDL 评分准则， 并将特殊注解合并到 fidldoc 工具中。 我们还可以向 fidl-lint 添加针对 fidldoc 语法的 lint 检查 工具或单独的工具中

文档和示例

完整示例如下所示。 请注意，此 API 目前不像下面这样；状态一直是 更改为一个错误，以作说明。

library fuchsia.io;

protocol File {
    /// Acquires a [`fuchsia.mem/Buffer`] representing this file, if
    /// there is one, with the requested access rights.
    ///
    /// ## Rights
    ///
    /// This method requires the following rights:
    ///
    /// * [`OPEN_RIGHT_WRITABLE`] if `flags` includes
    ///   [`VMO_FLAG_WRITE`].
    /// * [`OPEN_RIGHT_READABLE`] if `flags` includes
    ///   [`VMO_FLAG_READ`] or [`VMO_FLAG_EXEC`].
    ///
    /// + request `flags` a bit field composing any of
    ///   `VMO_FLAG_READ`, `VMO_FLAG_WRITE`, or `VMO_FLAG_EXEC`.
    /// - response `buffer` the requested [`fuchsia.mem/Buffer`], or
    ///     null if there was an error, or the buffer does not exist.
    /// * error a `zx.status` value indicating success or failure.
    /// * see [Filesystem architecture][fs-arch] for further details.
    ///
    /// [fs-arch]: https://fuchsia.dev/fuchsia-src/concepts/filesystems/filesystems
    GetBuffer(uint32 flags) ->
        (fuchsia.mem.Buffer? buffer) error zx.status;
};

请注意，按照惯例，您只需将第一个引用链接到 元素。 链接了上面对 VMO_FLAG_READ 的第一个引用，第二个引用已链接 。

向后兼容性

没有严重的向后兼容性问题。 当前文档使用 C++ 样式 |param| 表示法指示形参和 返回值。 可以相对轻松地进行更改。

性能

这将增加用户输入量，从而影响开发者的开发速度， 了解详情。

缺点、替代方案和未知问题

这种假设确实比没有内容形式更有意义 一种格式。 因此，缺点很少。

替代方案可能包括其他 API 文档格式。 Java 使用 Javadoc，后者非常冗长，并且依赖于内联 HTML。 开发者对此感到非常痛苦。 其他语言则使用 RST。 不过，这种流行程度越来越少开发者只需 自己熟悉的 Markdown 值得注意的是，LLVM 项目正在从 RST 迁移到 Markdown。

我们考虑过使用 Markdown 的其他变体。 我们决定使用 CommonMark，因为它是最符合其要求且 标准化。 需要其代码在其他 Markdown 渲染系统中运行的开发者 编写的文档注释应同时符合 CommonMark 和 目标系统

我们考虑过没有发明新语法来关联已记录的实体。 考虑的备选方案包括：

• 自动检测。 其他情境下自动检测机制的经验表明 但他们很少检测到开发者的意图。 此外，自动检测功能可防止工具显示 链接是错误的。 因此，我们将自动检测工作推迟到未来日期进行。
• 使用现有语法。 这种方法存在与自动检测相同的问题， 但也没那么糟糕 如果我们使用 fuchsia.io/NodeInfo 作为语法， 则链接不存在，我们只能获取代码 字体。 我们希望获得能够检测损坏链接的工具，而不是 行为

我们今后应考虑使用但目前不涵盖的内容 RFC，包括：

• 将图片或流程图嵌入生成的文档的方法。
• 将自动选中的示例嵌入文档的方法。

先验技术和参考资料

此方案深受 Rust 文档样式的影响 和 Kotlin。