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 man 頁，並且當工具為了簡潔而截斷它時（例如，當它們提取第一行或第一個句子時），它會讀起來更好。
關於包宣告的註釋應提供通用的包文件。這些註釋可以很簡短，例如 sort 包的簡要說明。
// Package sort provides primitives for sorting slices and user-defined
// collections.
package sort
它們也可以很詳細，例如 gob 包的概述。該包為需要大量介紹性文件的包使用另一種約定：包註釋放在自己的檔案 doc.go 中，其中只包含這些註釋和一個包子句。
在編寫任何大小的包註釋時，請記住，它的 第一句話將出現在 godoc 的 包列表中。
未與頂級宣告相鄰的註釋將從 godoc 的輸出中省略，但有一個例外。以單詞 “BUG(who)” 開頭的頂級註釋被識別為已知錯誤，幷包含在包文件的“Bugs”部分。 “who”部分應該是可以提供更多資訊的某人的使用者名稱。例如，這是 bytes 包中的一個已知問題。
// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.
有時，結構體欄位、函式、型別甚至整個包變得多餘或不必要，但必須保留以與現有程式相容。要指示一個識別符號不應被使用，請在其 doc 註釋中新增一個段落，該段落以“Deprecated:”開頭，後跟有關棄用的資訊。
Godoc 在將註釋轉換為 HTML 時使用一些格式規則。
-
後續的文字行被視為同一段落的一部分；您必須留一個空行來分隔段落。
-
預格式化文字必須相對於周圍的註釋文字進行縮排（請參閱 gob 的 doc.go 中的示例）。
-
URL 將轉換為 HTML 連結；不需要特殊的標記。
請注意，這些規則都不要求您做任何不尋常的事情。
事實上，godoc 的最小方法最棒的一點在於它的易用性。因此，大量的 Go 程式碼，包括所有標準庫，都已經遵循了這些約定。
您自己的程式碼只需包含上述註釋即可呈現良好的文件。安裝在 $GOROOT/src/pkg 中的任何 Go 包以及任何 GOPATH 工作區都可以透過 godoc 的命令列和 HTTP 介面訪問，您還可以透過 -path 標誌指定其他要索引的路徑，或者只需在源目錄中執行 “godoc .” 。有關更多詳細資訊，請參閱 godoc 文件。
下一篇文章：Introducing Gofix
上一篇文章：Gobs of data
部落格索引