# go doc與godoc ## go doc `go doc`命令可以打印附于Go語言程序實體上的文檔。我們可以通過把程序實體的標識符作為該命令的參數來達到查看其文檔的目的。 **插播：**所謂Go語言的程序實體，是指變量、常量、函數、結構體以及接口。而程序實體的標識符即是代表它們的名稱。標識符又分非限定標識符和限定標識符。其中，限定標識符一般用于表示某個代碼包中的程序實體或者某個結構體類型中的方法或字段。例如，標準庫代碼包`io`中的名為`EOF`的變量用限定標識符表示即`io.EOF`。又例如，如果我有一個`sync.WaitGroup`類型的變量`wg`并且想調用它的`Add`方法，那么可以這樣寫`wg.Add()`。其中，`wg.Add`就是一個限定標識符，而后面的`()`則代表了調用操作。 下面說明怎樣使用`go doc`命令。先來看一下`go doc`命令課結束的標記。 _表0-5 ```go doc```命令的標記說明_ 標記名稱 | 標記描述 ---------- | ------- -c | 加入此標記后會使`go doc`命令區分參數中字母的大小寫。默認情況下，命令是大小寫不敏感的。 -cmd | 加入此標記后會使`go doc`命令同時打印出`main`包中的可導出的程序實體（其名稱的首字母大寫）的文檔。默認情況下，這部分文檔是不會被打印出來的。 -u | 加入此標記后會使`go doc`命令同時打印出不可導出的程序實體（其名稱的首字母小寫）的文檔。默認情況下，這部分文檔是不會被打印出來的。 這幾個標記的意圖都非常簡單和明確，大家可以根據實際情況選用。 `go doc`命令可以后跟一個或兩個參數。當然，我們也可以不附加任務參數。如果不附加參數，那么`go doc`命令會試圖打印出當前目錄所代表的代碼包的文檔及其中的包級程序實體的列表。 例如，我要在goc2p項目的`loadgen`代碼包所在目錄中運行`go doc`命令的話，那么就會是這樣： ```bash hc@ubt:~/golang/goc2p/src/loadgen$ go doc package loadgen // import "loadgen" func NewGenerator( caller lib.Caller, timeoutNs time.Duration, lps uint32, durationNs time.Duration, resultCh chan *lib.CallResult) (lib.Generator, error) ``` 如果你需要指定代碼包或程序實體，那么就需要在`go doc`命令后附上參數了。例如，只要我本地的goc2p項目的所在目錄存在于GOPATH環境變量中，我就可以在任意目錄中敲入`go doc loadgen`。如此得到的輸出一定是與上面那個示例一致的。 看過`loadgen`代碼包中源碼的讀者會知道，其中只有一個可導出的程序實體，即`NewGenerator`函數。這也是上述示例中如此輸出的原因。該代碼包中的結構體類型`myGenerator`是不可導出，但是我們只需附加`-u`標記便可查看它的文檔了： ```bash hc@ubt:~$ go doc -u loadgen.myGenerator type myGenerator struct { caller lib.Caller // 調用器。 timeoutNs time.Duration // 處理超時時間，單位：納秒。 lps uint32 // 每秒載荷量。 durationNs time.Duration // 負載持續時間，單位：納秒。 concurrency uint32 // 并發量。 tickets lib.GoTickets // Goroutine票池。 stopSign chan byte // 停止信號的傳遞通道。 cancelSign byte // 取消發送后續結果的信號。 endSign chan uint64 // 完結信號的傳遞通道，同時被用于傳遞調用執行計數。 callCount uint64 // 調用執行計數。 status lib.GenStatus // 狀態。 resultCh chan *lib.CallResult // 調用結果通道。 } 載荷發生器的實現。 func (gen *myGenerator) Start() func (gen *myGenerator) Status() lib.GenStatus func (gen *myGenerator) Stop() (uint64, bool) func (gen *myGenerator) asyncCall() func (gen *myGenerator) genLoad(throttle <-chan time.Time) func (gen *myGenerator) handleStopSign(callCount uint64) func (gen *myGenerator) init() error func (gen *myGenerator) interact(rawReq *lib.RawReq) *lib.RawResp func (gen *myGenerator) sendResult(result *lib.CallResult) bool ``` 如此一來，`loadgen.myGenerator`類型的文檔、字段和方法都盡收眼底。注意，這里我們使用到了限定標識符。下面再進一步，如果你只想查看`loadgen.myGenerator`類型的`init`方法的文檔，那么只要續寫這個限定標識符就可以了，像這樣： ```bash hc@ubt:~$ go doc -u loadgen.myGenerator.init func (gen *myGenerator) init() error 初始化載荷發生器。 ``` 注意，結構體類型中的字段的文檔是無法被單獨打印的。另外，`go doc`命令根據參數查找代碼包或程序實體的順序是：先Go語言根目錄（即GOROOT所環境變量指定的那個目錄）后工作區目錄（即GOPATH環境變量包含的那些目錄）。并且，在前者或后者中，`go doc`命令的查找順序遵循字典序。因此，如果某個工作區目錄中的代碼包與標準庫中的包重名了，那么它是無法被打印出來的。`go doc`命令只會打印出第一個匹配的代碼包或程序實體的文檔。 我們在前面說過，`go doc`命令還可以接受兩個參數。這是一種更加精細的指定代碼包或程序實體的方式。一個顯著的區別是，如果你想打印標準庫代碼包`net/http`中的結構體類型`Request`的文檔，那么可以這樣敲入`go doc`命令： ```bash go doc http.Request ``` 注意，這里并沒有寫入`net/http`代碼包的導入路徑，而只是寫入了其中的最后一個元素`http`。但是如果你把`http.Request`拆成兩個參數（即` http Request`）的話，命令程序就會什么也查不到了。因為這與前一種用法的解析方式是不一樣的。正確的做法是，當你指定兩個參數時，作為第一個參數的代碼包名稱必須是完整的導入路徑，即：在敲入命令`go doc net/http Request`后，你會得到想要的結果。 最后，在給定兩個參數時，`go doc`會打印出所有匹配的文檔，而不是像給定一個參數時那樣只打印出第一個匹配的文檔。這對于查找只有大小寫不同的多個方法（如`New`和`new`）的文檔來說非常有用。 ## godoc 命令`godoc`是一個很強大的工具，同樣用于展示指定代碼包的文檔。在Go語言的1.5版本中，它是一個內置的標準命令。 該命令有兩種模式可供選擇。如果在執行命令時不加入`-http`標記，則該命令就以命令行模式運行。在打印純文本格式的文檔到標準輸出后，命令執行就結束了。比如，我們用命令行模式查看代碼包fmt的文檔： ```bash hc@ubt:~$ godoc fmt ``` 為了節省篇幅，我們在這里略去了文檔查詢結果。讀者可以自己運行一下上述命令。在該命令被執行之后，我們就可以看到編排整齊有序的文檔內容了。這包括代碼包`fmt`及其中所有可導出的包級程序實體的聲明、文檔和例子。 有時候我們只是想查看某一個函數或者結構體類型的文檔，那么我們可以將這個函數或者結構體的名稱加入命令的后面，像這樣： ```bash hc@ubt:~$ godoc fmt Printf ``` 或者： ```bash hc@ubt:~$ godoc os File ``` 如果我們想同時查看一個代碼包中的幾個函數的文檔，則僅需將函數或者結構體名稱追加到命令后面。比如我們要查看代碼包`fmt`中函數`Printf`和函數`Println`的文檔： ```bash hc@ubt:~$ godoc fmt Printf Println ``` 如果我們不但想在文檔中查看可導出的程序實體的聲明，還想看到它們的源碼，那么我們可以在執行`godoc`命令的時候加入標記`-src`，比如這樣： ```bash hc@ubt:~$ godoc -src fmt Printf ``` Go語言為程序使用示例代碼設立了專有的規則。我們在這里暫不討論這個規則的細節。只需要知道正因為有了這個專有規則，使得`godoc`命令可以根據這些規則提取相應的示例代碼并把它們加入到對應的文檔中。如果我們想在查看代碼包`net`中的結構體類型`Listener`的文檔的同時查看關于它的示例代碼，那么我們只需要在執行命令時加入標記`-ex`。使用方法如下： ```bash hc@ubt:~$ godoc -ex net/http FileServer ``` 注意，我們在使用`godoc`命令時，只能把代碼包和程序實體的標識符拆成兩個參數。也就是說，`godoc`命令不支持前文所述的`go doc`命令的單參數用法。 在實際的Go語言環境中，我們可能會遇到一個命令源碼文件所產生的可執行文件與代碼包重名的情況。比如，這里介紹的標準命令`go`和官方代碼包`go`。現在我們要明確的告訴`godoc`命令要查看可執行文件go的文檔，我們需要在名稱前加入`cmd/`前綴： ```bash hc@ubt:~$ godoc cmd/go ``` 另外，如果我們想查看HTML格式的文檔，就需要加入標記`-html`。當然，這樣在命令行模式下的查看效果是很差的。但是，如果仔細查看的話，可以在其中找到一些相應源碼的鏈接地址。 一般情況下，`godoc`命令會去Go語言根目錄和環境變量GOPATH包含的工作區目錄中查找代碼包。我們可以通過加入標記`-goroot`來制定一個Go語言根目錄。這個被指定的Go語言根目錄僅被用于當次命令的執行。示例如下： ```bash hc@ubt:~$ godoc -goroot="/usr/local/go" fmt ``` 現在讓我們來看看另外一種模式。如果我們在執行命令時加上`-http`標記則會啟用另一模式。這種模式被叫做Web服務器模式，它以Web頁面的形式提供Go語言文檔。 我們使用如下命令啟動這個文檔Web服務器： ```bash hc@ubt:~/golang/goc2p$ godoc -http=:6060 ``` 標記`-http`的值`:6060`表示啟動的Web服務器使用本機的6060端口。之后，我們就可以通過在網絡瀏覽器的地址欄中輸入[http://localhost:6060](http://localhost:6060)來查看以網頁方式展現的Go文檔了。  _圖0-1 本機的Go文檔Web服務首頁_ 這與[Go語言官方站點](http://golang.org)的Web服務頁面如出一轍。這使得我們在不方便訪問Go語言官方站點的情況下也可以查看Go語言文檔。并且，更便利的是，通過本機的Go文檔Web服務，我們還可以查看所有本機工作區下的代碼的文檔。比如，goc2p項目中的代碼包`pkgtool`的頁面如下圖：  _圖0-2 goc2p項目中的pkgtool包的Go文檔頁面_ 現在，我們在本機開啟Go文檔Web服務器，端口為9090。命令如下: ```bash hc@ubt:~$ godoc -http=:9090 -index ``` 注意，要使用`-index`標記開啟搜索索引。這個索引會在服務器啟動時創建并維護。如果不加入此標記，那么無論在Web頁面還是命令行終端中都是無法進行查詢操作的。 索引中提供了標識符和全文本搜索信息（通過正則表達式為可搜索性提供支持）。全文本搜索結果顯示條目的最大數量可以通過標記`-maxresults`提供。標記`-maxresults`默認值是10000。如果不想提供如此多的結果條目，可以設置小一些的值。甚至，如果不想提供全文本搜索結果，可以將標記`-maxresults`的值設置為0，這樣服務器就只會創建標識符索引，而根本不會創建全文本搜索索引了。標識符索引即為對程序實體名稱的索引。 正因為在使用了`-index`標記的情況下文檔服務器會在啟動時創建索引，所以在文檔服務器啟動之后還不能立即提供搜索服務，需要稍等片刻。在索引為被創建完畢之前，我們的搜索操作都會得到提示信息“Indexing in progress: result may be inaccurate”。 如果我們在本機用`godoc`命令啟動了Go文檔Web服務器，且IP地址為192.168.1.4、端口為9090，那么我們就可以在另一個命令行終端甚至另一臺能夠與本機聯通的計算機中通過如下命令進行查詢了。查詢命令如下： ```bash hc@ubt:~$ godoc -q -server="192.168.1.4:9090" Listener ``` 命令的最后為要查詢的內容，可以是任何你想搜索的字符串，而不僅限于代碼包、函數或者結構體的名稱。 標記`-q`開啟了遠程查詢的功能。而標記`-server="192.168.1.4:9090"`則指明了遠程文檔服務器的IP地址和端口號。實際上，如果不指明遠程查詢服務器的地址，那么該命令會自行將地址“:6060”和“golang.org”作為遠程查詢服務器的地址。這兩個地址即是默認的本機文檔Web站點地址和官方的文檔Web站點地址。所以執行如下命令我們也可以查詢到標準庫的信息： ```bash hc@ubt:~$ godoc -q fmt ``` 命令`godoc`還有很多可用的標記，但在通常情況下并不常用。讀者如果有興趣，可以在命令行環境下敲入`godoc`并查看其文檔。 至于怎樣才能寫出優秀的代碼包文檔，我在《Go并發編程實戰》的5.2節中做了詳細說明。