| RFC-0183：SDK 库文档 | |
|---|---|
| 状态 | 已接受 |
| 区域 |
|
| 说明 | 定义 SDK 中库的参考文档的要求。 |
| 问题 | |
| Gerrit 更改 | |
| 作者 | |
| 审核人 | |
摘要
定义添加到 SDK 的库的文档要求。
设计初衷
大多数 Fuchsia 代码都设计为以源代码形式使用。虽然有时 //docs 目录或源目录中会有 README.md 文件，但开发者通常需要参考源代码来了解特定库的功能以及如何使用它。
此方法不适用于操作系统及其众多支持库的消费者。开发者希望能够参考网页，了解总体概览和各个函数的低级别用法。
利益相关方
教员：neelsa@google.com
审核人员：mangini@google.com、mkearney@google.com、hjfreyer@google.com、ccherubino@google.com
咨询对象：sebmarchand@google.com、surajmahotra@google.com、dschuyler@google.com、jeremymanson@google.com、yifeit@google.com、computerdruid@google.com、nickvander@google.com、tmandry@google.com、theosiu@google.com、wilkinsonclay@google.com、kyol@google.com、pineapple@google.com
共同化：不适用
设计
此 RFC 定义了用于记录 SDK 库的规则和位置：
- 添加到公开 SDK 或合作伙伴 SDK 的新库必须具有公开（或合作伙伴 SDK 的合作伙伴限制）参考文档。
- 文档应面向 SDK 用户，但如果明确指明，也可以引用 fuchsia.git-only 概念。
- 文档必须足够详尽，以便开发者无需查看源代码或头文件即可使用这些库。
- 负责库代码的开发者将负责生成和维护参考的内容。
- 如果库的语言支持，则应通过 //tools/docsgen 基础架构生成参考文档。如果不支持，开发者可以选择一种格式或技术，只要它可以在 fuchsia.dev 上投放即可（如需最新建议，请发送电子邮件至 api-council@fuchsia.dev）。
就本文档而言，“参考文档”是指对现有函数和对象的说明以及如何使用这些函数和对象的说明。它假设读者对系统有良好的工作知识，并且了解库的总体目标。这与概述和教程等更高级别的文档形成对比。
此 RFC 未定义：
- 对概览和教程等更高级别文档的要求。
- 有关优秀图书馆参考资料中必须包含的内容的详细标准。
随着库文档的不断完善，未来的 RFC 将定义用于生成、设置格式和维护库参考文档的标准。
FIDL 参考文档将继续使用 fidldoc 基础架构生成。
实现
从接受此 RFC 开始，库文档规则将适用于添加到 SDK 中的新库。
该团队将逐步记录 SDK 中已有的库。这项工作的机制尚未确定。
缺点、替代方案和未知因素
此要求可能会延迟将有用的库添加到 SDK 的时间。但如果没有可用的参考，就可能无法充分发挥新库的优势。
避免为来源（例如源代码文档注释）或最终呈现形式（例如文档包含的内容及其组织方式）定义格式，很可能意味着初始添加项会选择不同的方法。我们可能需要在未来重新整理这些内容。此提案旨在避免使初始文档工作复杂化，并在确定更详细的要求之前让团队积累一些经验。
在先技术和参考资料
其他操作系统供应商维护着一些网站，其中记录了其面向开发者的系统库。例如，
- Android Automotive 库，Android 上的系统库示例。
- Uniscribe，Microsoft Windows 附带的国际化库示例。
- ARKit，Apple 的一个系统库示例。
许多编程语言都有用于从源代码生成文档的工具，例如 Java 的 javadoc 和 Rust 的 rustdoc。Doxygen 是最常用的 C++ 文档工具，而 Fuchsia 团队成员也为 Clang 中的 clang-doc 做出了贡献。
FIDL 具有 RFC-0043 和 RFC-0055 中定义的现有标准和格式。
Fuchsia Rust 团队维护了 Fuchsia Rust 库的参考信息。在 SDK 支持 Rust 之前，这些内容托管在单独的网站上。
Fuchsia 有通用的文档标准。