| 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、theosiu
社交：不适用
设计
此 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 文档标准。