godoc指令文檔

上一文我們展示了怎麼在go文檔中插入可測試的代碼，那麼怎麼使用go文檔呢。我們找對應的文檔來學習下。先來學習下godoc指令。

下文是對https://pkg.go.dev/golang.org/x/tools/cmd/godoc的翻譯。

Godoc會提取并為Go程式生成文檔。

它會運作一個web伺服器并把文檔以web網頁的形式展示。

godoc -http=:6060
           

使用：

flags有：

-v
	複雜輸出模式
-timestamps=true
	在路徑清單上展示時間戳
-index
	啟用辨別符和全文搜尋索引
	(如果沒有設定 -index 的話，是搜不了文檔内容的)
-index_files=""
	glob模式指定的索引檔案。如果不是空的，就會以排序過的順序從這些檔案中讀取索引
-index_throttle=0.75
	索引的限速值：設定為0意味着不配置設定時間給索引器(索引器永遠不會終止)，1.0則意味
	着全速建立索引(在索引建立期間，其他goroutine可能争不到cpu時間)
-index_interval=0
	建立索引的間隔時間；0值會設定它為5分鐘，負值則隻會在啟動時建立索引一次。
-play=false
	是否啟用 playground
-links=true
	把辨別符連結到他們的聲明
-write_index=false
	把索引寫入檔案；檔案名必須使用-index_files來指定
-maxresults=10000
	能展示的全文搜尋結果的最大數量
	（如果maxresults<=0，不會建構全文索引）
-notes="BUG"
	regular expression matching note markers to show
	(e.g., "BUG|TODO", ".*")
-goroot=$GOROOT
	Go的根路徑
-http=addr
	HTTP服務的位址(例如'127.0.0.1:6060'或者僅':6060')
-analysis=type,pointer
	逗号分隔的要展示的分析的清單
	"type": 展示辨別符的resolution，類型資訊，方法集，‘實作’，以及靜态被調用
	"pointer": 展示channel兩端，調用方和動态被調(明顯地更慢)
	細節見 https://golang.org/lib/godoc/analysis/help.html
-templates=""
	路徑包含可選的模版檔案。如果設定了這個項，對應路徑可以提供替代$GOROOT/lib/godoc中檔案的模版檔案
-url=path
	把會為對應路徑HTTP請求提供的資料輸出到标準輸出
-zip=""
	指定提供了檔案系統的zip檔案。為空則不啟用
           

預設的，godoc會看它在$GOROOT和$GOPATH(如果設定了)裡頭找到的package。可以通過使用-goroot選項，提供另一個$GOROOT來改變這個行為。

當設定了-index選項，就會維護一個搜尋索引。這個索引會在啟動時被建立。

索引會包含辨別符和全文搜尋資訊(可以通過正規表達式來搜尋)。可以通過-maxresults來設定可展示的全文搜尋結果的最大數量；如果設定為0，就不會有任何全文結果，僅會有辨別符索引而不會建立全文搜尋索引。

預設地，godoc會使用系統的GOOS/GOARCH。你可以指定URL參數 "GOOS"和"GOARCH"來為目标系統設定在web頁上的輸出。

godoc對應web頁面的展示模式可以通過"m"URL參數來控制，它接受逗号分隔的flag清單：

all 為所有聲明都展示文檔，而不是僅對外公開的那些。

methods 展示所有嵌入的方法，而不是僅展示那些未公開的匿名字段

src 展示源代碼，而不是提取的文檔

flat 展示平鋪(而不是縮緊)的目錄清單，也就是全路徑

例如，https://golang.org/pkg/math/big/?m=all 會為big package的所有(而不僅是公開的)聲明生成文檔。

預設的，godoc處理的是底層OS的檔案系統上的檔案。也可以通過-zip選項提供一個.zip檔案，讓godoc處理這個zip代表的檔案系統。存儲在.zip檔案中的檔案路徑必須使用斜杆(’/’)作為路徑分割符；并且必須是unrooted的。$GOROOT（或者-goroot）必須被設定到包含Go根路徑的.zip檔案目錄路徑。比如，對于一個由以下指令建立的.zip檔案：

zip -r go.zip $HOME/go
           

你可以像這樣運作godoc：

godoc -http=:6060 -zip=go.zip -goroot=$HOME/go
           

Godoc文檔是使用go/doc package轉換為HTML或者文本的；如果想知道提取規則的話，見https://golang.org/pkg/go/doc/#ToHTML。Godoc也會展示可以被testing包運作的示例代碼；約定見https://golang.org/pkg/testing/#hdr-Examples。見“Godoc：歸檔Go代碼”來學習怎麼為godoc寫很棒的注釋：https://golang.org/doc/articles/godoc_documenting_go_code.html。