ehlxr/gopl-zh.github.com
1
0
Fork 0
mirror of https://github.com/gopl-zh/gopl-zh.github.com.git synced 2024-11-04 21:43:42 +00:00
Code Issues Projects Releases Wiki Activity

ch10-7-4: review

Browse Source
This commit is contained in:
chai2010 2016-01-08 21:46:10 +08:00
parent e7ec8acc1f
commit cc15c02622
1 changed files with 12 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
ch10/ch10-07-4.md
View File

@ -1,8 +1,8 @@
### 10.7.4. 包文檔 ### 10.7.4. 包文檔
Go的編碼風格鼓勵爲每個包提供良好的文檔. 包中每個導出的成員和包聲明前都應該包含添加目的和用法説明的註釋. Go語言的編碼風格鼓勵爲每個包提供良好的文檔。包中每個導出的成員和包聲明前都應該包含目的和用法説明的註釋。
Go中包文檔註釋一般是完整的句子, 第一行是包的摘要説明, 註釋後僅跟着包聲明語句. 函數的參數或其他的標識符併不需要額外的引號或其他標記註明. 例如, 下面是 fmt.Fprintf 的文檔註釋. Go語言中包文檔註釋一般是完整的句子，第一行是包的摘要説明，註釋後僅跟着包聲明語句。註釋中函數的參數或其它的標識符併不需要額外的引號或其它標記註明。例如，下面是fmt.Fprintf的文檔註釋。
```Go ```Go
// Fprintf formats according to a format specifier and writes to w. // Fprintf formats according to a format specifier and writes to w.
@ -10,13 +10,13 @@ Go中包文檔註釋一般是完整的句子, 第一行是包的摘要説明,
func Fprintf(w io.Writer, format string, a ...interface{}) (int, error) func Fprintf(w io.Writer, format string, a ...interface{}) (int, error)
``` ```
Fprintf 函數格式化的細節在 fmt 包文檔中描述. 如果註釋後僅跟着包聲明語句, 那註釋對應整個包的文檔. 包文檔對應的註釋隻能有一個(譯註: 其實可以多個, 它們會組合成一個包文檔註釋.), 可以出現在任何一個源文件中. 如果包的註釋內容比較長, 可以當到一個獨立的文件中; fmt 包註釋就有 300 行之多. 這個專門用於保證包文檔的文件通常叫 doc.go. Fprintf函數格式化的細節在fmt包文檔中描述。如果註釋後僅跟着包聲明語句，那註釋對應整個包的文檔。包文檔對應的註釋隻能有一個（譯註：其實可以有多個，它們會組合成一個包文檔註釋），包註釋可以出現在任何一個源文件中。如果包的註釋內容比較長，一般會放到一個獨立的源文件中；fmt包註釋就有300行之多。這個專門用於保存包文檔的源文件通常叫doc.go。
好的文檔併不需要面面俱到, 文檔本身應該是簡潔但可不忽略的. 事實上, Go的風格喜歡簡潔的文檔, 併且文檔也是需要想代碼一樣維護的. 對於一組聲明語句, 可以同一個精鍊的句子描述, 如果是顯而易見的功能則併不需要註釋. 好的文檔併不需要面面俱到，文檔本身應該是簡潔但可不忽略的。事實上，Go語言的風格更喜歡簡潔的文檔，併且文檔也是需要像代碼一樣維護的。對於一組聲明語句，可以用一個精鍊的句子描述，如果是顯而易見的功能則併不需要註釋。
在本書中, 隻要空間允許, 我們之前很多包聲明都包含了註釋文檔, 但你可以從標準庫中發現很多更好的例子. 有兩個工具可以幫到你. 在本書中，隻要空間允許，我們之前很多包聲明都包含了註釋文檔，但你可以從標準庫中發現很多更好的例子。有兩個工具可以幫到你。
`go doc` 命令打印包的聲明和每個成員的文檔註釋, 下面是整個包的文檔: 首先是`go doc`命令，該命令打印包的聲明和每個成員的文檔註釋，下面是整個包的文檔：
``` ```
$ go doc time $ go doc time
@ -34,7 +34,7 @@ type Time struct { ... }
...many more... ...many more...
``` ```
或者是包的一個成員的註釋文檔: 或者是某個具體包成員的註釋文檔：
``` ```
$ go doc time.Since $ go doc time.Since
@ -44,7 +44,7 @@ func Since(t Time) Duration
It is shorthand for time.Now().Sub(t). It is shorthand for time.Now().Sub(t).
``` ```
或者是包的一個方法的註釋文檔: 或者是某個具體包的一個方法的註釋文檔：
``` ```
$ go doc time.Duration.Seconds $ go doc time.Duration.Seconds
@ -53,7 +53,7 @@ func (d Duration) Seconds() float64
Seconds returns the duration as a floating-point number of seconds. Seconds returns the duration as a floating-point number of seconds.
``` ```
該工具併不需要輸入完整的包導入路徑或正確的大小寫. 下面的命令打印 encoding/json 包的 (*json.Decoder).Decode 方法的文檔: 該命令併不需要輸入完整的包導入路徑或正確的大小寫。下面的命令將打印encoding/json包的`(*json.Decoder).Decode`方法的文檔：
``` ```
$ go doc json.decode $ go doc json.decode
@ -63,15 +63,12 @@ func (dec *Decoder) Decode(v interface{}) error
it in the value pointed to by v. it in the value pointed to by v.
``` ```
第二個工具, 令人睏惑的也是名叫 godoc, 提供可以相互交叉引用的 HTML 頁面, 但是包含和 `go doc` 相同以及更多的信息. 10.1 節演示了 time 包的文檔, 11.6 節將看到godoc演示可以交互的示例程序. godoc 的在線服務 https://godoc.org, 包含了成韆上萬的開源包的檢索工具. 第二個工具，名字也叫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://localhost:8000/pkg 頁面:
``` ```
$ godoc -http :8000 $ godoc -http :8000
``` ```
其中 `-analysis=type` 和 `-analysis=pointer` 命令行標誌參數用於打開文檔和代碼中關於靜態分析的結果. 其中`-analysis=type`和`-analysis=pointer`命令行標誌參數用於打開文檔和代碼中關於靜態分析的結果。