本页面包含“Google 文档季”接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- ScummVM
- 技术文档工程师：
- b-gent
- 项目名称：
- 通过 Doxygen 改进源代码文档
- 项目时长：
- 标准时长（3 个月）
Project description
最新的 ScummVM API（源代码）文档发布在以下网址：https://doxygen.scummvm.org/modules.html
但遗憾的是，它在很多方面都有所欠缺：
1) 几乎没有结构，所有信息都在同一级别浮动。
2) C++ 元素的文档记录与其中某些元素根本没有记录。这是该组织所提出的主要问题之一。
3) 输出中仍然显示过时和已弃用的内容。
4) Doxygen 标记的语言和用法应更加一致。为此，需要制定一套规则，这些规则可作为此项目未来文档样式指南的基础。
5) 可以对此页面上使用的 doxygen CSS 进行改进，使其更类似于 ScummVM 网站：https://www.scummvm.org
所有这些问题都可以通过文档季计划解决。
本季的 Google 文档应用附有我在项目中打开的 PR 草稿，以展示我提议的一些潜在改进： https://github.com/scummvm/scummvm/pull/2361 请查看说明，了解其所含内容的详细信息并查看差异。
PR 大致涉及以下内容：
1) 我认为，对于潜在的新贡献者以及查看当前 API 文档的每个人而言，目前最令人困惑的地方是缺乏结构。引入结构化 API 文档可以提高可读性、可查找性，进而提高文档集的易用性。这就是我的 PR 将 doxygen 群组引入“common”文件夹中的所有头文件的原因。例如，借助这种新结构，如果有人想要查找操作系统相关 API 的文档，他们可以在导航中轻松找到。
2) 设置了新的 doxygen 配置文件，以支持构建此文档。
3)“links.doxyfile”文件，整个文档中使用的所有链接都可作为单一来源。使用 Doxygen 时的一种实用机制。
4) 经过修改的 doxygen CSS。此项目当前取自另一个开源项目，这只是起点。理想情况下，Doxygen 页面的外观和风格应该与 ScummVM 网页大体一致。
公关不涵盖但绝对需要努力的是内容本身。我的意思是，确定未记录的代码的基本部分、记录不足的代码部分，或者应从文档中移除的过时代码部分。我之前没有参与过这个项目，需要导师的指导才能实现这个目标。
当然，是否实施 PR 的任何措施取决于与组织商讨。我的想法是，行动比文字更生动，因此我决定展示我能做些什么，而不仅仅是在应用中进行描述。
组织提供了此项目的以下大致时间安排 第 1 周、后端 - 第 1 周、第 1 周和第 1 周（第 1 周、第 1 周、第 1 周、第 1 周、第 1 周、第 1 周、第 1 周、第 1 周、第 1 周、第 1 周和 1 周 1 项讨论和审核）
我建议的唯一更改是从结构开始，如前所述。可以在第 1 周和第 2 周以及 Doxygen 构建设置（大部分已经完成）和 Doxygen 皮肤刷新完成这项工作。之后，我认为最合理的做法是，与导师一起探讨不同的领域，找出问题并改进 Doxygen 文档。
我认为这是一个标准长度的项目，但我确信在 GSoD 项目结束后还可以进行与 API 文档相关的其他改进。例如，起草一份文档样式指南并将其添加到 Wiki 中，以便贡献者了解他们应该如何记录自己添加的代码。
我很乐意在 GSoD 结束后帮助处理此类任务。我相信 ScummVM 可以请一名技术文档工程师，负责确保其 API 文档的质量和易用性。我还发现将来还有其他文档项目可以帮助您处理，例如创建有关如何使用插件的指南。