回到简体

ch10/ch10-07-4.md

@@ -1,8 +1,8 @@
-### 10.7.4. 包文檔
+### 10.7.4. 包文档
 
-Go語言的編碼風格鼓勵爲每個包提供良好的文檔。包中每個導出的成員和包聲明前都應該包含目的和用法説明的註釋。
+Go语言的编码风格鼓励为每个包提供良好的文档。包中每个导出的成员和包声明前都应该包含目的和用法说明的注释。
 
-Go語言中包文檔註釋一般是完整的句子，第一行是包的摘要説明，註釋後僅跟着包聲明語句。註釋中函數的參數或其它的標識符併不需要額外的引號或其它標記註明。例如，下面是fmt.Fprintf的文檔註釋。
+Go语言中包文档注释一般是完整的句子，第一行是包的摘要说明，注释后仅跟着包声明语句。注释中函数的参数或其它的标识符并不需要额外的引号或其它标记注明。例如，下面是fmt.Fprintf的文档注释。
 
 ```Go
 // 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)
 ```
 
-Fprintf函數格式化的細節在fmt包文檔中描述。如果註釋後僅跟着包聲明語句，那註釋對應整個包的文檔。包文檔對應的註釋隻能有一個（譯註：其實可以有多個，它們會組合成一個包文檔註釋），包註釋可以出現在任何一個源文件中。如果包的註釋內容比較長，一般會放到一個獨立的源文件中；fmt包註釋就有300行之多。這個專門用於保存包文檔的源文件通常叫doc.go。
+Fprintf函数格式化的细节在fmt包文档中描述。如果注释后仅跟着包声明语句，那注释对应整个包的文档。包文档对应的注释只能有一个（译注：其实可以有多个，它们会组合成一个包文档注释），包注释可以出现在任何一个源文件中。如果包的注释内容比较长，一般会放到一个独立的源文件中；fmt包注释就有300行之多。这个专门用于保存包文档的源文件通常叫doc.go。
 
-好的文檔併不需要面面俱到，文檔本身應該是簡潔但可不忽略的。事實上，Go語言的風格更喜歡簡潔的文檔，併且文檔也是需要像代碼一樣維護的。對於一組聲明語句，可以用一個精鍊的句子描述，如果是顯而易見的功能則併不需要註釋。
+好的文档并不需要面面俱到，文档本身应该是简洁但可不忽略的。事实上，Go语言的风格更喜欢简洁的文档，并且文档也是需要像代码一样维护的。对于一组声明语句，可以用一个精炼的句子描述，如果是显而易见的功能则并不需要注释。
 
-在本書中，隻要空間允許，我們之前很多包聲明都包含了註釋文檔，但你可以從標準庫中發現很多更好的例子。有兩個工具可以幫到你。
+在本书中，只要空间允许，我们之前很多包声明都包含了注释文档，但你可以从标准库中发现很多更好的例子。有两个工具可以帮到你。
 
-首先是`go doc`命令，該命令打印包的聲明和每個成員的文檔註釋，下面是整個包的文檔：
+首先是`go doc`命令，该命令打印包的声明和每个成员的文档注释，下面是整个包的文档：
 
 ```
 $ go doc time
@@ -34,7 +34,7 @@ type Time struct { ... }
 ...many more...
 ```
 
-或者是某個具體包成員的註釋文檔：
+或者是某个具体包成员的注释文档：
 
 ```
 $ go doc time.Since
@@ -44,7 +44,7 @@ func Since(t Time) Duration
 	It is shorthand for time.Now().Sub(t).
 ```
 
-或者是某個具體包的一個方法的註釋文檔：
+或者是某个具体包的一个方法的注释文档：
 
 ```
 $ 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.
 ```
 
-該命令併不需要輸入完整的包導入路徑或正確的大小寫。下面的命令將打印encoding/json包的`(*json.Decoder).Decode`方法的文檔：
+该命令并不需要输入完整的包导入路径或正确的大小写。下面的命令将打印encoding/json包的`(*json.Decoder).Decode`方法的文档：
 
 ```
 $ go doc json.decode
@@ -63,12 +63,12 @@ func (dec *Decoder) Decode(v interface{}) error
 	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 ，包含了成千上万的开源包的检索工具。
 
-你也可以在自己的工作區目録運行godoc服務。運行下面的命令，然後在瀏覽器査看 http://localhost:8000/pkg 頁面：
+你也可以在自己的工作区目录运行godoc服务。运行下面的命令，然后在浏览器查看 http://localhost:8000/pkg 页面：
 
 ```
 $ godoc -http :8000
 ```
 
-其中`-analysis=type`和`-analysis=pointer`命令行標誌參數用於打開文檔和代碼中關於靜態分析的結果。
+其中`-analysis=type`和`-analysis=pointer`命令行标志参数用于打开文档和代码中关于静态分析的结果。