| 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、theoslayiu@google.com、theoslayiu
社交：不适用
设计
此 RFC 定义了记录 SDK 库的规则和位置：
- 添加到公共 SDK 或合作伙伴 SDK 的新库必须具有公开参考文档（对于合作伙伴 SDK，仅限合作伙伴访问）参考文档。
- 本文档应面向 SDK 用户，但如果用户明确指出此类概念，则可以参考仅限 fuchsia.git 的概念。
- 这些文档必须足以让开发者使用这些库，而无需查看源代码或头文件。
- 负责库代码的开发者将负责生成和维护参考的内容。
- 如果 //tools/docsgen 基础架构支持此库的语言，则应生成参考文档。如果不受支持，开发者可以选择格式或技术，只要格式或技术可以在 fuchsia.dev 上提供（如需获取最新建议，请发送电子邮件至 api-council@fuchsia.dev）。
在本文中，“参考文档”是对存在哪些函数和对象以及如何使用它们的一些说明。本指南假定您对系统有很好的了解，并且了解该库的总体目标。这与概览和教程等更高级别的文档形成了鲜明对比。
此 RFC 不会定义以下内容：
- 对概要文档（例如概览和教程）的要求。
- 关于优秀的库参考中必须包含内容的详细标准。
预计随着库文档的不断完善，未来的 RFC 将会定义有关库参考文档的生成、格式设置和维护的标准。
我们将继续使用 fidldoc 基础架构生成 FIDL 参考文档。
实现
从接受此 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 文档标准。