本頁針對 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」資料夾中的所有標頭檔案。使用者可以透過這個新架構，輕鬆找到 OS 相關 API 的文件 (例如)，
2) 設定新的 Doxygen 設定檔，以便建立這份文件。
3)「links.doxyfile」檔案，從文件中使用的所有連結都屬於單一來源。使用 Doxygen 時的有用機制。
4) 經過修改的 Doxygen CSS。這項操作目前取自其他開放原始碼專案，只是起點。在理想情況下，Doxygen 網頁的外觀和風格應與 ScummVM 網頁更加一致或較不相同。
公關事務不包括內容，但確實需要加以處理的是內容本身。我指的是找出未記錄的程式碼基本部分、未充分記錄的程式碼，或是應從文件中移除的過舊程式碼部分。由於我先前從未在這項專案中工作，因此需要指導老師提供指導。
當然，我們是否會導入 PR 等任何項目，才會與機構進行討論。我的想法是說這些動作比字詞更大聲，因此我決定先在應用程式中描述我能做些什麼，而不只是在應用程式中說明。
該機構為這項專案提供了下列大致時間表： 第 1 週/第 9 週 (9 月 14 日)、提案討論及審查 第 1 週 (9/14) 第 1 週/第 1 週/第 1 週/第 1 週/第 1 週/第 1 週/第 1 週/第 1 週/第 1 週/第 1 週/第 1 週/第 1 週/第 1 週/第 1 週；一般平台/圖表
我提議的唯一變更就是按照先前所述，從架構著手。這項作業可在第 1 週和第 2 週完成，包括 Doxygen 版本設定 (大部分已完成) 和 Doxygen 皮膚更新。之後，我同意在輔導老師逐一找出問題，並改善氧化劑處理流程的準確性。
我看到的專案是標準時間，但我可以在 GSoD 專案完成後，針對 API 說明文件進行其他改善。舉例來說，想出一份文件樣式指南，並將其加入維基，讓協作者瞭解該如何記錄自己新增的程式碼。
我很高興在 GSoD 結束後處理這類工作。我確定 ScummVM 可以請技術文件編寫者負責確保其 API 文件的品質和可用性。我也發現，日後還有一些文件專案可以為您提供協助，例如製作外掛程式使用指南。