Go 部落格
Godoc：記載 Go 程式碼文件
[請注意，2022 年 6 月：有關記載 Go 程式碼文件的最新準則，請參閱「Go 文件註解」。]
Go 專案重視文件。文件是讓軟體易於使用和維護的重要部分。當然文件必須寫得精彩且正確，但撰寫和維護起來也必須容易。理想情況下，文件應與程式碼本身相結合，如此文件會隨著程式碼演進。程式設計人員越容易產生優良文件，對所有人而言越好。
為此，我們開發了 godoc 文件工具。這篇文章說明了 godoc 處理文件的方式，並說明如何運用我們的慣例和工具為專案撰寫優良文件。
Godoc 會剖析 Go 原始碼（包括註解），並產生 HTML 或純文字的說明文件。最終結果是緊密結合與所描述程式碼的說明文件。例如，透過 godoc 的網路介面，您可以從 函式的說明文件 到其 實作 只需按一下。
Godoc 的概念類似 Python 的 Docstring 和 Java 的 Javadoc，但其設計更簡單。Godoc 讀取的註解並不是語言建構 (如 Docstring)，也不需要具有自己的機器可讀語法 (如 Javadoc)。Godoc 註解只是好的註解，即使沒有 godoc，您也想讀的類型。
慣例很簡單：要說明類型、變數、常數、函式，甚至套件，請撰寫一個規律註解，直接放在其宣告之前，且不要用空行隔開。接著 Godoc 會將此註解顯示為文字，並放在其說明的項目旁邊。例如，以下是 fmt 套件的 Fprint 函式的說明文件。
// Fprint formats using the default formats for its operands and writes to w.
// Spaces are added between operands when neither is a string.
// It returns the number of bytes written and any write error encountered.
func Fprint(w io.Writer, a ...interface{}) (n int, err error) {
請注意，此註解是一個完整的句子，從其所描述的元素名稱開始。這個重要的慣例讓我們能夠產生各種格式的說明文件，從純文字到 HTML 到 UNIX 手冊頁，並在工具基於簡潔性而擷取它時 (例如，擷取第一行或第一個句子時)，讓它更好讀。
套件宣告的註解應該提供一般的套件說明文件。這些註解可以很簡短，就像 sort 套件的簡要說明。
// Package sort provides primitives for sorting slices and user-defined
// collections.
package sort
它們也可以像 gob 套件 的概觀一樣詳細。該套件對需要大量簡介說明文件的套件使用另一種慣例：將套件註解放在自己的檔案中，doc.go，它只包含這些註解和一個套件子句。
撰寫任何規模的套件註解時，請記住它的 第一句話 會出現在 godoc 的 套件清單 中。
沒有緊鄰頂層宣告的註解不會出現在 godoc 的輸出的，例外情況有一個。從單字 "BUG(who)” 開始的頂層註解被識別為已知的錯誤，並包含在套件說明文件的「錯誤」部分。"who” 部分應該是能夠提供更多資訊的使用者名稱。例如，以下是 bytes 套件 中已知的問題。
// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.
有時候結構欄位、函式、類型，甚至整個套件會變得多餘或不必要，但必須保留它以符合現有程式的相容性。若要標示一個識別項不應該使用，請加入一個段落到它的文件註解中，該段落從「已棄用：」開始，後面接續一些關於棄用的資訊。
Godoc 在將註解轉換為 HTML 時使用一些格式化規則。
-
後續的文字行被視為同一段落的組成部分；您必須留一個空行來分隔段落。
-
預先格式化的文字必須相對於周圍的註解文字縮進（請參閱 gob 的 doc.go 取得範例）。
-
網址將會轉換成 HTML 連結；不需要特殊標記。
請注意，這些規則並不要求您做任何特別的事情。
事實上，godoc 最棒的一點是如何容易使用。因此，許多 Go 程式碼，包含所有的標準函式庫，都符合慣例。
您的程式碼只要如上所述包含註解，就可以顯示良好的文件。安裝於 $GOROOT/src/pkg 裡的任何 Go 套件以及任何 GOPATH 工作空間都可經由 godoc 的命令列和 HTTP 介面存取，而您可以透過 -path 旗標為編製索引指定其他路徑，或僅在來源目錄中執行 "godoc ."。如需更多詳細資訊，請參閱 godoc 文件。