本页面包含有关 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 未涵盖但绝对需要改进的是内容本身。我的意思是，确定未记录的代码的基本部分、记录不足的代码部分或者应从文档中移除的过时代码部分。我之前没有参与过这个项目，需要导师的指导才能实现这个目标。
当然，是否实施来自 PR 的任何方案取决于与组织的讨论。我的想法是，行动比言语更重要，因此我决定展示我的功能，而不是只在应用中进行描述。
组织为此项目提供了以下大致时间安排 （第 1 周/主要任务/第 1 周） （第 0 周（在 9 月/14 日之前） 第 1 周（9 月 14 日之前） Doxygen 构建设置 第 2 周（9/21）更新 Doxygen 皮肤（低优先级） 第 3 周（9/28 周）常用代码（OSystem、FS、周 1）（第 1 周/第 1 周）（通用代码 2、第 1 周/2 周）
我唯一提议的更改是在结构上开始，如前面提到的那样。这项工作可在第 1 周和第 2 周内完成，同时进行 Doxygen 构建设置（大部分已经完成）和 Doxygen 皮肤更新。之后，我认为最合理的做法是与导师一起探讨不同的领域，找出问题并改进 Doxygen 文档。
我认为这是一个标准长度的项目，但我确定在 GSoD 项目完成后，还可以进行其他与 API 文档相关的改进。例如，拟定文档样式指南并将其添加到 Wiki 中，以便贡献者了解应如何记录所添加的代码。
我很乐意在 GSoD 结束后帮助处理此类任务。我确信 ScummVM 可以聘请技术文档工程师，以确保其 API 文档的质量和易用性良好。我还可以看到日后还有一些其他的文档项目可以帮到您，例如创建有关如何使用插件的指南。