gopl-zh.github.com/ch10/ch10-07-4.md

### 10.7.4. 包文檔

Go的編碼風格鼓勵爲每個包提供良好的文檔. 包中每個導出的成員和包聲明前都應該包含添加目的和用法説明的註釋.

Go中包文檔註釋一般是完整的句子, 第一行是包的摘要説明, 註釋後僅跟着包聲明語句. 函數的參數或其他的標識符併不需要額外的引號或其他標記註明. 例如, 下面是 fmt.Fprintf 的文檔註釋.

```Go
// Fprintf formats according to a format specifier and writes to w.
// It returns the number of bytes written and any write error encountered.
func Fprintf(w io.Writer, format string, a ...interface{}) (int, error)
```

Fprintf 函數格式化的細節在 fmt 包文檔中描述. 如果註釋後僅跟着包聲明語句, 那註釋對應整個包的文檔. 包文檔對應的註釋隻能有一個(譯註: 其實可以多個, 它們會組合成一個包文檔註釋.), 可以出現在任何一個源文件中. 如果包的註釋內容比較長, 可以當到一個獨立的文件中; fmt 包註釋就有 300 行之多. 這個專門用於保證包文檔的文件通常叫 doc.go.

好的文檔併不需要面面俱到, 文檔本身應該是簡潔但可不忽略的. 事實上, Go的風格喜歡簡潔的文檔, 併且文檔也是需要想代碼一樣維護的. 對於一組聲明語句, 可以同一個精鍊的句子描述, 如果是顯而易見的功能則併不需要註釋.

在本書中, 隻要空間允許, 我們之前很多包聲明都包含了註釋文檔, 但你可以從標準庫中發現很多更好的例子. 有兩個工具可以幫到你.

`go doc` 命令打印包的聲明和每個成員的文檔註釋, 下面是整個包的文檔:

```
$ go doc time
package time // import "time"

Package time provides functionality for measuring and displaying time.

const Nanosecond Duration = 1 ...
func After(d Duration) <-chan Time
func Sleep(d Duration)
func Since(t Time) Duration
func Now() Time
type Duration int64
type Time struct { ... }
...many more...
```

或者是包的一個成員的註釋文檔:

```
$ go doc time.Since
func Since(t Time) Duration

	Since returns the time elapsed since t.
	It is shorthand for time.Now().Sub(t).
```

或者是包的一個方法的註釋文檔:

```
$ go doc time.Duration.Seconds
func (d Duration) Seconds() float64

	Seconds returns the duration as a floating-point number of seconds.
```

該工具併不需要輸入完整的包導入路徑或正確的大小寫. 下面的命令打印 encoding/json 包的 (*json.Decoder).Decode 方法的文檔:

```
$ go doc json.decode
func (dec *Decoder) Decode(v interface{}) error

	Decode reads the next JSON-encoded value from its input and stores
	it in the value pointed to by v.
```

第二個工具, 令人睏惑的也是名叫 godoc, 提供可以相互交叉引用的 HTML 頁面, 但是包含和 `go doc` 相同以及更多的信息. 10.1 節演示了 time 包的文檔, 11.6 節將看到godoc演示可以交互的示例程序. godoc 的在線服務 https://godoc.org, 包含了成韆上萬的開源包的檢索工具.

You can also run an instance of godoc in your workspace if you want to  browse your own packages. Visit http://localhost:8000/pkg in your browser while running this command:

你也可以在自己的工作區目録允許 godoc 服務. 運行下面的命令, 然後在瀏覽器査看 http://localhost:8000/pkg 頁面:

```
$ godoc -http :8000
```

其中 `-analysis=type` 和 `-analysis=pointer` 命令行標誌參數用於打開文檔和代碼中關於靜態分析的結果.