本頁將詳細說明 Google Season of Docs 接受的技術文件寫作專案。
專案摘要
- 開放原始碼組織：
- 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 請參閱說明，瞭解相關內容和差異。
以下是 PR 大致涵蓋的內容：
1) 我認為目前對潛在的新貢獻者，以及一般查看目前 API 文件的使用者來說，最令人困惑的是缺乏結構。導入結構化 API 說明文件可改善可讀性、可尋性，進而提升文件集的可用性。因此，我的提交內容會在「common」資料夾中的所有標頭檔案中引入 Doxygen 群組。有了這個新結構，如果有人想找出與 OS 相關的 API 說明文件，就能輕鬆在導覽中找到。
2) 已設定新的 Doxygen 設定檔，以啟用此說明文件。
3) 「links.doxyfile」檔案，其中所有文件集使用的所有連結都可以使用單一來源。使用 Doxygen 時相當實用的機制。
4) 經過修改的 Doxygen CSS。目前這項功能是從其他開放原始碼專案取得，只是個起點。在理想情況下，Doxygen 網頁的外觀和風格應該與 ScummVM 網頁一致。
內容本身是 PR 未涵蓋但絕對需要處理的部分。這意味著，我的意思是找出程式碼中未記載的基本部分、未充分記載的片段，或是應從說明文件中移除的過時程式碼部分。由於我之前未曾參與這項專案，因此需要導師的指導才能完成這項工作。
當然，我們是否會實作 PR 中的任何內容，取決於與機構的討論結果。我的想法是「行動勝於空談」，因此我決定展示我能做的事情，而不是只在申請中說明。
該組織為本專案提供了以下大致的時間表： 週數 主要工作 第 0 週 (9/14 之前) 討論提案並進行審查 第 1 週 (9/14) 設定 Doxygen 建構 第 2 週 (9/21) 更新 Doxygen 外觀 (低優先順序) 第 3 週 (9/28) 通用程式碼 - OSystem、FS、資料結構、字串等 第 4 週 (10/05) 通用程式碼 - 繼續進行 第 5 週 (10/12) 引擎 - 通用程式碼和範例引擎 第 6 週 (10/19) 圖形 第 7 週 (10/26) 音訊 第 8 週 (11/02) 影片、圖片 第 9 週 (11/09) 後端 - 平台、圖形、事件 第 10 週 (11/23) 後端 - 繼續進行 第 11 週 (11/30) 專案摘要和提交
我建議唯一的改變是先處理如先前提到的架構。這項作業可在第 1 週和第 2 週進行，再搭配 Doxygen 版本設定 (大部分已已完成) 以及 Doxygen 翻新。之後，我同意與導師逐一討論不同領域，找出問題並改善 Doxygen 說明文件。
我認為這是標準長度的專案，但我相信在 GSoD 專案結束後，您還可以進行其他與 API 文件相關的改善。舉例來說，製作說明文件樣式指南並加入維基百科中，讓貢獻者瞭解應該如何記錄自己新增的程式碼。
在 GSoD 結束後，我很樂意協助你完成這類工作。我相信 ScummVM 可以聘請技術文件撰稿者，確保 API 文件的品質和可用性高。我還發現，未來還有其他文件專案需要協助，例如建立如何使用外掛程式的指南。