貢獻類別參考文件

類別參考是一系列說明引擎公開 API 的文章。內容涵蓋各類別、方法、屬性與全域物件的詳細說明，供腳本撰寫時使用。類別參考可於官方線上文件、側邊欄與 Godot 編輯器的說明選單中查閱。

隨著引擎持續成長、功能增加或調整，類別參考的部分內容可能會過時，因此需要補充新的說明與範例。雖然開發者上傳 Pull Request 時需同步撰寫類別參考，但不是每位程式設計師都擅長技術寫作。因此，非常需要像你這樣的貢獻者協助補足與優化現有或缺漏的參考內容。

類別參考的來源

由於類別參考同時提供於線上文件與 Godot 編輯器中，必須注意兩者內容同步。因此，Godot 主儲存庫被視為唯一正本，所有類別參考文件皆以此為依據並在該處維護。

警告

你**不應該**編輯文件儲存庫的 classes/ 資料夾裡的 .rst 檔。這些檔案是自動產生的，由專案維護者手動同步。請繼續閱讀以了解正確編輯類別參考的方法。

在主儲存庫中，類別參考以 XML 檔案形式儲存，每個公開的類別或全域物件各有一份。大部分檔案位於 doc/classes/，但部分模組也有自己的文件，這些會在 modules/<module_name>/doc_classes/ 目錄下。如需詳細瞭解如何編輯 XML，請參考類別參考入門。

也參考

有關 Git 使用與 Pull Request 工作流程的詳細說明，請參考 Pull Request 工作流程頁面。該頁面大部分說明同樣適用於本文件儲存庫。

若你想將類別參考從英文翻譯為其他語言，請參考編輯器與說明文件本地化。本教學亦有 YouTube 影片教學提供。

重要： 如果你打算進行大範圍修改，請在 godot-docs 儲存庫建立 Issue，或於現有 Issue 下留言，讓其他人知道你正負責某個類別的內容。

可參與的內容

最適合開始貢獻的內容，就是你最熟悉的類別。這能確保所新增的說明基於實務經驗與相關知識，而不只是方法或屬性的名稱。我們建議不要添加簡略或敷衍的描述，即使這樣做看來很方便。類似內容會掩蓋實際的文件需求，也不易被自動偵測出來。

也參考

遵循這個原則非常重要，這也讓我們能開發出各類輔助工具協助貢獻者，例如類別參考的完成度追蹤器。你可以用它快速找出哪些文件頁面缺少說明。

若你決定補充某個類別文件，但對其中部分方法不了解，沒關係，可以先略過。請於送出 Pull Request 時，列出所有你暫時未補充說明的方法，其他編寫者會協助補齊。

You can still look at the methods' implementation in Godot's source code on GitHub. If you have doubts, feel free to ask on the Godot Forum and Godot Contributors Chat.

警告

除非僅需進行微幅修改（例如更正錯字），否則不建議直接用 GitHub 網頁編輯器修改類別參考的 XML 檔案。該編輯器缺乏良好的 XML 編輯功能（例如自動縮排），也無法根據審查意見修正 Commit。

此外你也無法如如何編輯類別 XML 所述，在引擎內或透過驗證腳本測試你的變更。

於引擎開發時更新類別參考

當你新增類別或修改現有引擎的 API 時，需要重新產生 doc/classes/ 內的 XML 檔案。

為此，你必須先編譯 Godot。請參考建置系統介紹頁面。接著，在 Godot 根目錄下，使用 --doctool 參數執行已編譯的 Godot 執行檔。例如在 64 位元 Linux 系統下，指令可能為：

./bin/godot.linuxbsd.editor.x86_64 --doctool

實際的檔案後綴可能有所不同，請詳閱文中連結以瞭解細節。

此時，doc/classes/ 內的 XML 檔案應該已同步至最新的 Godot Engine 功能。你可透過 git diff 指令檢查變更內容。

請僅將和你 API 相關的變更一併提交。如有不相關的檔案被修改，可用 git checkout 取消。若發現有無關檔案被更新，也可以考慮回報。理想情況下，這些動作應只產生你自己做的變更。

接著，你需要為所有新產生的項目補上說明內容。