API 文档可读性评分准则

概览

本文档包含有关为 Fuchsia 编写 API 文档的指导。它 既适用于面向公众的 API（通过 SDK 提供的 API），也适用于 紫红色内部。公开的 API 文档将由 API 委员会，以确保遵循此 评分准则。

总体评论规则

在大多数情况下，文档应遵循相应语言的样式指南， 评论。如果本文档中的某条规则与 语言特定的规则，请遵循本文档的指南。在某些情况下， 以针对特定语言的规则为准；这些特殊情况 。

此处提供了相应语言指南的链接 在 Fuchsia 代码库中使用： C 和 C++， Rust、 Java、 Kotlin。 我们还建议您阅读 Google 的 API 指南 文档。

谨慎沟通

Fuchsia 文档已公开，应 以中性的技术语气撰写有一些明确的限制 ，但这些内容并不是详尽无遗的 - 请使用 你的判断真好！

  • 请勿引用专有信息。这包括个人 包括个人身份信息和 身份验证密钥。
  • 切勿使用脏话或其他可能具有攻击性的语言（如 例如“stupid”）

常规样式

  • Fuchsia 使用美式英语，并遵循 Fuchsia 文档标准和 风格指南
  • 请勿明确列出作者。作者信息很快就会过时 开发者会改用不同的项目考虑提供维护人员 文件，但请注意，此文件也会过期。
  • 针对预期显示效果优化代码（例如，使用 Markdown 或 Javadoc 代码 ）。

只有在没有语言特有的做法时，才应用以下规则 指南：

  • 文档应紧挨着它记录的元素。
  • 为评论使用 Markdown。Markdown 的风格就是 最有可能使用该 API 的工具。
    • 为代码块使用反引号，而不要使用 4 个空格的缩进。
  • 所有评论都应使用完整的句子。

API 元素

  • 面向公众的 API 元素是面向开发者提供的元素 通过 SDK所有面向公众的 API 元素（包括但不限于 方法、类、字段、类型）都必须包含说明。内部库 应记录在案；如果不符合，则有充分的理由

  • 所有参数都必须包含说明，除非该说明是 与类型和名称重复。

    • 如果从类型中无法明显看出参数的合法值是什么， 请考虑更改类型例如，{-1, 0, 1}不如 包含 {LESS_THAN, EQUAL_TO, GREATER_THAN} 的枚举。
    • 否则，请为所有可能的输入值记录 API 行为。 我们不建议使用未记录的值。

  • 所有返回值都必须包含说明，除非该说明是 与类型和名称重复。

    • 如果方法或函数返回其返回值类型的子集，请将 子集。
    • 记录返回的所有错误以及可能出现这些错误的情况 生成的内容。
    • 例如，如果该方法的返回类型为 zx_status_t，且只有 会返回 ZX_OK 和 ZX_ERR_INVALID_ARGS，则您的文档必须声明 明确指定。
    • 如果某个返回值的含义无法立即显现出来， 必须记录下来。例如，如果某个方法返回 ZX_OK， 进行记录如果某个方法返回字符串的长度， 进行记录。

  • 所有可能抛出的异常都必须包含说明，该说明中必须包含以下内容： 除非在类型和 名称。

    • 某些第三方代码不会一致地记录异常。它可能会 很难（或不可能）记录依赖于此类 API。可以接受“尽力而为”；我们可以解决由此造成的问题 出现了。
    • 记录异常是否可恢复，以及如果可以，如何恢复 。

  • 对于任何可扩展的 API 元素，请指明它们是否是 以及对想要扩展的用户的要求

    • 如果 API 因内部原因（例如测试）而可扩展， 这一点。例如，如果您允许 扩展，从而轻松创建测试替身。

  • 记录已弃用的 API 元素。

    • 有关已弃用的 API 元素的文档必须说明对用户的要求 不需要使用 API 来完成
    • 应明确记录停用该 API 的计划（如果有）。
    • 如果对某个 API 元素的弃用状态的说明会减少 考虑提供指向 API 文档的 更多信息，包括网址和错误标识符。

API 行为

记录面向用户的不变量，以及先决条件和后置条件。

  • 通常，请确保通过断言 / 测试来强制执行这些测试 条件。
  • 需要用户明确操作的先决条件和后置条件应 进行记录。例如，如果 Init() 方法存在，请提供相关文档 需要在其他任何操作发生之前调用
  • 参数或返回值之间的相关性（例如，1 必须小于 ）进行记录。

并发

记录具有内部状态的 API 的并发属性。

  • FIDL 服务器可能会以不可预测的顺序执行请求。文档 应考虑到这可能会影响调用方行为的情况 观察。
  • 每个具有内部状态的 API 都属于以下某个类别。 使用以下术语记录哪一个： <ph type="x-smartling-placeholder">
      </ph>
    • 线程安全：这意味着调用 API 的各个元素 （例如类中的方法）就其他并发而言是原子性的 过程。调用方无需使用任何外部 同步（例如，调用方不应必须获取 方法调用的时长）。您仍然可以将 API 描述为 如果调用方需要使用外部同步 对其他线程可见的 API 实例的引用（例如， 设置并获取指向具有 atomic 的类实例的全局指针 操作）。
    • 线程不安全：这意味着所有方法都必须使用外部线程。 以确保保持不可变（例如， （通过锁定来强制执行排除）。
    • Thread-hostile：表示不应访问 API 元素 （例如，它具有依赖于 在后台对静态数据的非同步访问，例如 strtok()。 其中应包含有关线程亲和性的文档（例如， 线程本地存储 (TLS)）。只有例外情况才能在 Fuchsia API 中使用。
    • 特殊：这表示可以正确并发使用此 API 需要仔细思考，请阅读相关文档。尤其是在 需要初始化实体，并在 特定方式
    • 不可变：其他四个类假定内部状态 可变且线程安全通过同步来保证。不可变 类看起来是恒定不变的，无需任何额外的同步， 必须对序列化 / 反序列化和 如何在线程之间共享对对象的引用。
  • 如果无法保证某个 API 会进展，则该 API 处于阻塞状态。文档 API 的屏蔽属性
    • 如果某个 API 阻止了 API，则文档必须声明对 除非屏蔽是导致该错误概率的低概率事件， 需要了解实施情况
      • 举例来说，在需要记录方法的阻塞行为时， 它会阻止在通道上等待响应。
      • 无需记录方法的阻塞情况的示例 也就是理论上锁资源耗尽， 高负载下的可能性。
    • 我们不能仅仅因为 API 需要很长时间才能 完成。不应将运行缓慢的算法记录为阻塞算法。
    • 只有当 API 的 非阻塞行为对其使用至关重要（例如，如果 API 会返回一个 Future）。
  • 如果 API 在其运行过程中可能安全中断，就会被视为可重入 API。 然后再次调用该脚本请记录 API。
    • API 可视为可重入。文档必须声明 API 不可再次参加。
  • 记录函数是否依赖线程本地存储 (TLS) 来 以及任何与之相关的先决条件和后置条件， 该 TLS（例如，它需要每个线程调用初始化程序一次）。

所有权

文档所有权和活跃度属性。

  • 对于存储超出 函数或者由该函数分配并传回给 或具有特定所有权限制的资源， 通过一组 API（即共享资源）、所有权和活跃性来观察 必须记录下来。
  • 记录负责释放所有关联资源的人员。
  • 在适当情况下，文档中应声明关于发布 这些资源。在内存分配时，这可能是一个特殊问题 API 的调用方与 API 的例程有所不同。
    • 语言应在其样式中指明默认所有权行为 指南。

null 性

所有参数和返回值都必须定义其 null 性属性（如果 它们属于可为 null 类型）。

  • 即便是在 Dart 中！
  • 在适当情况下，以“可为 null”的形式引用参数并将返回值（可以 包含 null）或 non-null（不得包含 null）。

单位

对于所有参数和返回类型，必须明确定义单位（无论是通过 文档或类型）。

最佳做法

本部分包含您在开发产品/服务时 撰写评论。其中包含观点，而不是给出的明确规则 。

  • 读者应该不必通过查看 API 的实现来确定 。考虑编写可供读者 根据文档独立实现您的 API。如果您需要提供 提供有关 API 工作原理的更多详细信息，创建并链接到其他文档 Fuchsia.dev 上的内容。
  • 避免使用读者可能不明显的术语（例如：“如果我 对这个 API 感兴趣，我能否知道这个词是什么意思？”）。如果 术语表特定于 Fuchsia 且未定义，请将其添加到词汇表中。
  • 避免使用缩写和首字母缩略词。如果需要使用它们，请加以说明。 如果缩写在业界被广泛使用（例如，"传播 控制协议 / 互联网协议"(TCP/IP)），则无需解释 但你应该考虑提供一个链接，提供更多背景信息。
  • 只要代码示例可能有用，就应加以考虑。正在提供 通常可以更清楚地说明模式。建议使用 API 示例 。
  • 应该在注释中明确说明如何使用您的 API。
    • 不妨考虑将示例编写为单独的程序并链接到这些程序，但 注意文档中的过时链接。
    • 示例都应能编译并运行。
  • 有人阅读文档的人提出一个问题时， 改进文档。
  • 始终能带来更多价值。不要重申类型签名已指示的内容。 “不要重复自己”(DRY) 原则同样适用。以下是 没用，因为相同的信息会重复两次：
 /**
  * Returns an instance of Foo.
  * @return an instance of Foo.
  */
 public Foo getFoo() { ... }
  • 同样，如果注释非常明显，请避免添加。例如，如果 属性由类型系统保证，您无需为其添加文档 。但请注意，您的 API 说明应该足够了 以实现独立实现
  • 考虑记录性能注意事项和资源消耗情况 但请注意，此类问题通常取决于实施 和随时间变化的情况，而方法的协定很可能会 保持不变请考虑在实现说明中添加此信息 / 版本说明。
  • 避免创建非复合单词的连贯性词语。例如“notready” 就是两个单词连在一起。使用适当的分隔符，例如“尚未就绪” “notReady”、“not_ready”或“not-ready”）。
  • 避免记录可能会随时间推移快速变化的特征， 否则这项功能可能会随时间推移而发生变化用户越多， 您提供给未来的维护者的灵活性越低。不过， 您意识到这可能无关紧要 行为另请参阅 Hyrum 定律。