本页面包含 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
在“文档季”项目期间，您可以解决所有这些问题。
此文档季申请随附我在项目中打开的一份草稿 PR，以展示我提出的一些潜在改进： https://github.com/scummvm/scummvm/pull/2361 请参阅该说明，详细了解其中包含的内容并查看差异。
大致来说，公关活动包括以下内容：
1) 我认为，对于潜在的新贡献者，以及查看当前 API 文档的每个人来说，目前最令人困惑的是缺乏条理性。引入结构化 API 文档有助于提高文档集的可读性和可搜索性，进而提高其易用性。因此，我的 PR 为“common”文件夹中的所有头文件引入了 doxygen 组。例如，通过这种新结构，如果用户想查找操作系统相关 API 的文档，就可以在导航中轻松找到该文档。
2) 设置一个新的 doxygen 配置文件，以支持构建此文档。
3)“links.doxyfile”文件，整个文档集中使用的所有链接都可以是单一来源的。在使用 doxygen 时，这是一个非常有用的机制。
4) 经过修改的 doxygen CSS。目前，此示例取自另一个开源项目，只是一个起点。理想情况下，doxygen 页面的外观和风格应与 ScummVM 网页大致一致。
预发布版本未涵盖但绝对需要改进的是内容本身。我的意思是，找出未记录的代码要点、记录不充分的代码要点，或者应从文档中移除的过时代码要点。我之前从未参与过此项目，因此需要导师的指导才能完成此任务。
当然，我们是否要实现 PR 中的任何内容，取决于与相关组织的讨论结果。我的想法是行动比文字更有说服力，所以我决定展示我能做些什么，而不只是在应用中进行描述。
该组织为此项目提供了以下大致时间表： 周 主要任务 第 0 周（9 月 14 日之前） 提案讨论和审核 第 1 周（9 月 14 日） 设置 Doxygen build 第 2 周（9 月 21 日） 刷新 Doxygen 皮肤（优先级较低） 第 3 周（9 月 28 日） 常用代码 - OSystem、FS、数据结构、字符串等 第 4 周（10 月 5 日） 常用代码 - 继续 第 5 周（10 月 12 日） 引擎 - 常用代码和示例引擎 第 6 周（10 月 19 日） 图形 第 7 周（10 月 26 日） 音频 第 8 周（11 月 2 日） 视频、图片 第 9 周（11 月 9 日） 后端 - 平台、图形、事件 第 10 周（11 月 23 日） 后端 - 继续 第 11 周（11 月 30 日） 项目摘要和提交
我建议的唯一更改是，先从结构着手，如前所述。这可在第 1 周和第 2 周内完成，同时进行 doxygen 构建设置（已基本完成）和 Doxygen 皮肤刷新。之后，我同意，最好与导师一起逐一检查不同的方面，以发现问题并改进 doxygen 文档。
我认为这是标准长度的项目，但我相信在 GSoD 项目完成后，您还可以改进与 API 文档相关的其他方面。例如，制定文档样式指南并将其添加到 Wiki 中，以便贡献者了解应如何为其添加的代码编写文档。
在 GSoD 结束后，我非常乐意帮助您处理此类任务。我相信 ScummVM 需要一位技术文档撰写者，确保其 API 文档质量优良且易于使用。我还了解到，未来还有其他文档项目需要我帮助您完成，例如制作有关如何使用插件的指南。