Go 部落格
Godoc: 文件化 Go 程式碼
[注意，2022 年 6 月]: 有關 Go 程式碼文件編寫的最新指南，請參閱“Go Doc Comments”。
Go 專案非常重視文件。文件是使軟體易於訪問和維護的重要組成部分。當然，文件必須寫得好並且準確，但也必須易於編寫和維護。理想情況下，它應該與程式碼本身緊密耦合，以便文件隨著程式碼一起演進。程式設計師編寫良好文件越容易，對每個人就越有利。
為此，我們開發了 godoc 文件工具。本文描述了 godoc 的文件化方法，並解釋瞭如何使用我們的約定和工具為您的專案編寫良好的文件。
Godoc 解析 Go 原始碼（包括註釋），並生成 HTML 或純文字格式的文件。最終結果是文件與它所描述的程式碼緊密耦合。例如，透過 godoc 的 Web 介面，您可以一鍵從函式的 文件導航到其 實現。
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)” 開頭的頂級註釋被識別為已知 bug，幷包含在包文件的“Bugs”部分中。“who”部分應是能夠提供更多資訊的人的使用者名稱。例如，這是來自 bytes 包 的一個已知問題
// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.
有時，結構體欄位、函式、型別，甚至整個包變得多餘或不再需要，但為了與現有程式相容必須保留。為了表明某個識別符號不應使用，在其文件註釋中新增一個段落，以“Deprecated:”開頭，後跟有關廢棄的一些資訊。
Godoc 在將註釋轉換為 HTML 時使用以下一些格式規則
-
後續的文字行被視為同一段落的一部分；您必須留一個空行來分隔段落。
-
預格式化文字必須相對於周圍的註釋文字進行縮排（示例請參見 gob 的 doc.go）。
-
URL 將被轉換為 HTML 連結；無需特殊標記。
請注意，這些規則都不需要您做任何特別的事情。
實際上，godoc 最小化方法最好的地方在於它非常易於使用。因此，很多 Go 程式碼，包括所有標準庫，都已經遵循了這些約定。
您的程式碼只需包含如上所述的註釋，即可呈現良好的文件。安裝在 $GOROOT/src/pkg 內的任何 Go 包以及任何 GOPATH 工作空間都已可透過 godoc 的命令列和 HTTP 介面訪問，您可以透過 -path 標誌或只需在原始碼目錄中執行 "godoc ." 來指定其他索引路徑。更多詳情請參閱 godoc 文件。