Go語言之Doc 文檔

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

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

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

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

從終端查看文檔

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

  hello go help doc
usage: go doc [-u] [-c] [package|[package.]symbol[.method]]

Doc prints the documentation comments associated with the item identified by its
arguments (a package, const, func, type, var, or method) followed by a one-line
summary of each of the first-level items "under" that item (package-level
declarations 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 doc
package lib // import "flysnow.org/hello/lib"

提供的常用庫，有一些常用的方法，方便使用

func Add(a, b int) int

在當前目錄執行go doc，輸出了當前目錄下的文檔信息。

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

  lib go doc json
package json // import "encoding/json"

Package json implements encoding and decoding of JSON as defined in RFC
4627. The mapping between JSON and Go values is described in the
documentation for the Marshal and Unmarshal functions.

See "JSON and Go" for an introduction to this package:
https://golang.org/doc/articles/json_and_go.html

func Compact(dst *bytes.Buffer, src []byte) error
func HTMLEscape(dst *bytes.Buffer, src []byte)
func Indent(dst *bytes.Buffer, src []byte, prefix, indent string) error
func Marshal(v interface{}) ([]byte, error)
func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)
func Unmarshal(data []byte, v interface{}) error
type Decoder struct{ ... }
    func NewDecoder(r io.Reader) *Decoder
type Delim rune
type Encoder struct{ ... }
    func NewEncoder(w io.Writer) *Encoder
type InvalidUTF8Error struct{ ... }
type InvalidUnmarshalError struct{ ... }
type Marshaler interface{ ... }
type MarshalerError struct{ ... }
type Number string
type RawMessage []byte
type 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.Decoder
package 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) *Decoder
func (dec *Decoder) Buffered() io.Reader
func (dec *Decoder) Decode(v interface{}) error
func (dec *Decoder) More() bool
func (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 lib

import "fmt"

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

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

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