【翻譯】Godoc：文檔化 Go 代碼

這是一個建立於 的文章，其中的資訊可能已經有所發展或是發生改變。

各位童鞋，愚人節好！由於鄙人愚鈍，過不了這種高端節日，所以就不過節了。
所以今天即不會有鄙人要改名叫 mikeghost 的訊息，也不會有諸如在 Android 上跑 iOS 應用的訊息出現，當然，大家更不需要穿越的有木有來閱讀本文。
生活還要繼續……
原文《Godoc: documenting Go code》在此：http://blog.golang.org/2011/03/godoc-documenting-go-code.html
—————-翻譯分割線—————-

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, error os.Error) {

留意這些注釋全部都是有它描述的元素名字的普通句子。這個重要的約定使我們可以產生各種不同格式的文檔，從純文字到 HTML，或者 UNIX 的 man 手冊；或為了使其更容易閱讀而進行截斷，例如只顯示第一行或者第一句的時候。

包上的注釋會提供關於包大致資訊的文檔。這個注釋可以很短，例如 sort 包的短短的描述：

// The sort package provides primitives for sorting arrays// and user-defined collections.package sort

也可以使用類似 gob package 那樣的詳細描述。這個包需要大量的介紹性文檔，而使用了其他約定：包的注釋在其doc.go檔案裡，包含了注釋和包的使用規定。

不論編寫任何大小的注釋，都要記得，第一句話將出現在 godoc 的 package list中。

與頂級定義不相鄰的注釋，會被 godoc 的輸出忽略，但有一個意外。以“BUG(who)”開頭的頂級注釋會被識別為已知的 bug，會被包含在包文檔的“Bugs”部分。“who”應當是能提供更進一步資訊的使用者的名字。例如，這是來自於bytes 包的一個已知問題：

// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.

Godoc 作為可執行命令時有些不同。它不會檢查指定的源碼，而是在屬於 Go 源碼的特殊的包“documentation”中尋找。“package documentation”的注釋作為命令文檔。例如，查看godoc documentation和與其對應的doc.go檔案。

用 Godoc 將注釋轉換為 HTML 時，有一些格式規則：

• 緊接著下一行的文本被認為是同一段的；你必須空出一行，來分隔段落。
• 預格式化文本必須在注釋符號內縮排（閱讀gob的doc.go作為例子）。
• 無序額外符號，URL 會被轉換為 HTML 連結。

注意，這些規則沒有哪個是需要你做超出通常要做的事情的範圍的。

事實上，godoc 最棒的地方就是它的易用性。這樣一來，許多 Go 代碼，包括許多標準庫，已經遵循這些約定。

可以用上面所描述的，將你自己的代碼中的注釋產生良好的文檔。 任何安裝在$GOROOT/src/pkg/的 Go 包，已經可以通過 godoc 的命令列和 HTTP 介面訪問，你也可以通過 -path 標識添加指定的路徑，或者在原始碼目錄執行“godoc .”。閱讀godoc documentation瞭解更多細節。