| 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 的概念（前提是这些概念已明确标识）。
- 文档必须足够详尽，让开发者无需查看源代码或头文件即可使用这些库。
- 负责库代码的开发者将负责生成和维护参考内容。
- 参考文档应由 //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 文档标准。