Go語言實戰筆記（三）| Go Doc 文檔

這是一個建立於 的文章，其中的資訊可能已經有所發展或是發生改變。

《Go語言實戰》讀書筆記，未完待續，歡迎關注公眾號flysnow_org，第一時間看後續筆記。

對於協作開發或者代碼共用來說，文檔是一個可以協助開發人員快速瞭解以及使用這些代碼的一個教程，文檔越全面，越詳細，入門越快，效率也會更高。

在Go語言中，Go為我們提供了快速產生文檔以及查看文檔的工具，讓我們可以很容易的編寫查看文檔。

Go提供了兩種查看文檔的方式，一種是使用go doc命令在終端查看，這種適用於使用VIM等工具在終端開發的人員，它們不用離開終端，既可以查看想查看的文檔，又可以編碼。

第二種方式，是使用瀏覽器查看的方式，通過godoc命令可以在本機啟動一個web服務，我們可以通過開啟瀏覽器，訪問這個服務來查看我們的Go文檔。

從終端查看文檔

這種方式適用於在終端開發的，它們一般不像離開終端，查完即可繼續編碼，這時候使用go doc命令是很不錯的選擇。

➜  hello go help docusage: go doc [-u] [-c] [package|[package.]symbol[.method]]Doc prints the documentation comments associated with the item identified by itsarguments (a package, const, func, type, var, or method) followed by a one-linesummary of each of the first-level items "under" that item (package-leveldeclarations for a package, methods for a type, etc.).Flags:    -c        Respect case when matching symbols.    -cmd        Treat a command (package main) like a regular package.        Otherwise package main's exported symbols are hidden        when showing the package's top-level documentation.    -u        Show documentation for unexported as well as exported        symbols and methods.

從以上可以看出，go doc的使用比較簡單，接收的參數是包名，或者以包裡的結構體、方法等。如果我們不輸入任何參數，那麼顯示的是目前的目錄的文檔，下面看個例子。

/* 提供的常用庫，有一些常用的方法，方便使用 */package lib// 一個加法實現// 返回a+b的值func Add(a,b int) int {    return a+b}

➜  lib go docpackage lib // import "flysnow.org/hello/lib"提供的常用庫，有一些常用的方法，方便使用func Add(a, b int) int

在目前的目錄執行go doc，輸出了目前的目錄下的文檔資訊。

除此之外，我們還可以指定一個包，就可以列出當前這個包的資訊，著包括文檔、方法、結構體等。

➜  lib go doc jsonpackage json // import "encoding/json"Package json implements encoding and decoding of JSON as defined in RFC4627. The mapping between JSON and Go values is described in thedocumentation for the Marshal and Unmarshal functions.See "JSON and Go" for an introduction to this package:https://golang.org/doc/articles/json_and_go.htmlfunc Compact(dst *bytes.Buffer, src []byte) errorfunc HTMLEscape(dst *bytes.Buffer, src []byte)func Indent(dst *bytes.Buffer, src []byte, prefix, indent string) errorfunc Marshal(v interface{}) ([]byte, error)func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)func Unmarshal(data []byte, v interface{}) errortype Decoder struct{ ... }    func NewDecoder(r io.Reader) *Decodertype Delim runetype Encoder struct{ ... }    func NewEncoder(w io.Writer) *Encodertype InvalidUTF8Error struct{ ... }type InvalidUnmarshalError struct{ ... }type Marshaler interface{ ... }type MarshalerError struct{ ... }type Number stringtype RawMessage []bytetype SyntaxError struct{ ... }type Token interface{}type UnmarshalFieldError struct{ ... }type UnmarshalTypeError struct{ ... }type Unmarshaler interface{ ... }type UnsupportedTypeError struct{ ... }type UnsupportedValueError struct{ ... }

以上是我們以json包為例，查看該包的文檔，從中我們可以看到它有一個名為Decoder的結構體，我們進一步查看這個結構體的文檔。

➜  lib go doc json.Decoderpackage json // import "encoding/json"type Decoder struct {    // Has unexported fields.}    A Decoder reads and decodes JSON values from an input stream.func NewDecoder(r io.Reader) *Decoderfunc (dec *Decoder) Buffered() io.Readerfunc (dec *Decoder) Decode(v interface{}) errorfunc (dec *Decoder) More() boolfunc (dec *Decoder) Token() (Token, error)func (dec *Decoder) UseNumber()

現在我們看到這個Decoder有很多方法,進一步查看這些方法的文檔，比如Decode。

➜  lib go doc json.Decoder.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.    See the documentation for Unmarshal for details about the conversion of JSON    into a Go value.

go doc使用就是這樣，一步步，縮小範圍，查看想看的那些包、結構體、介面或者函數方法的文檔。

線上瀏覽文檔

go doc終端查看的方式，雖然也很便捷，不過效率不高，並且沒有查看細節以及進行跳轉，為此Go為我們提供了基於瀏覽器使用的網頁方式進行瀏覽API 文檔，我們只用點點滑鼠，就可以查看了，還可以在方法、包等之間進行跳轉，更簡潔方便。

要想啟動一個Web線上API文檔服務很簡單，使用godoc就可以了。

➜  lib godoc -http=:6060

後面的http是要指定Web服務監聽的IP和Port，運行後，我們就可以開啟瀏覽器，輸入http://127.0.0.1:6060進行訪問了，你會發現開啟的頁面，和GoLang的官方網站一樣，沒錯，這個其實就是官網的一個拷貝，但是包的文檔http://127.0.0.1:6060/pkg/會和官網不一樣,你自己啟動的這個服務，是基於你電腦上GOROOT和GOPATH這兩個路徑下的所有包產生的文檔，會比官網只是標準庫的文檔要多。

線上瀏覽API文檔非常方便，只需要滑鼠點擊就可以了，也可以點擊藍色的超連結在方法、結構、介面以及包等之間跳轉，還可以查看對應的原始碼，範例程式碼，很方便，我們經常用的也是這個線上瀏覽方式。

產生自己的文檔

Go文檔工具，還有一個亮點，就是可以支援開發人員自己寫的代碼，只要開發人員按照一定的規則，就可以自動產生文檔了。

在我們編碼中，文檔就是注釋，Go語言採用了和C、Java差不多的注釋風格。一種是雙斜線的方式，一種是斜線和星號的方式。

/* 提供的常用庫，有一些常用的方法，方便使用 */package lib// 一個加法實現// 返回a+b的值func Add(a,b int) int {    return a+b}

這還是我們剛剛那個例子，例子中文檔的編寫的兩種風格。想要為哪些標識符生車文檔，就在哪些標識符之前，使用注釋的方式，加入到代碼中即可。

現在我們不管是用go doc，還是godoc都可以看到我們剛剛注釋的文檔了。

添加文檔樣本

我們在看很多官方API文檔的時候，可以在文檔裡看到一些例子，這些例子會告訴我們怎麼使用API，以及這個例子列印的輸出是什麼，我覺得這個非常好，這樣看函數文檔看不懂的，可以參考這個例子，那麼對於我們自己寫的API，怎麼給API文檔添加範例程式碼呢？

這裡我參考了官方的原始碼，總結了測試了一下，發現可行，這裡分享一下。

1. 範例程式碼必須單獨存放在一個檔案中，檔案名稱字為example_test.go。
2. 在這個go檔案裡，定義一個名字為Example的函數，參數為空白
3. 樣本的輸出採用注視的方式，以//Output:開頭，另起一行，每行輸出佔一行。

說了這三個規則，下面通過一個例子更直觀的瞭解。

package libimport "fmt"func Example() {    sum:=Add(1,2)    fmt.Println("1+2=",sum)    //Output:    //1+2=3}

這就是為剛剛那個Add函數寫的範例程式碼，我們運行godoc就可以看到結果了。

範例程式碼文檔

Go的文檔工具非常強大，更多功能，我們可以使用協助命令查看。這裡再推薦一個比較不錯的第三方的API文檔網站，收錄了包括官方在內的很多Go庫，可以直接跳轉，關聯原始碼，非常方便。https://gowalker.org/

《Go語言實戰》讀書筆記，未完待續，歡迎關注公眾號flysnow_org，第一時間看後續筆記。