golang文档解析

查看文档

golang提供了godoc命令方便我们查看文档。文档是由注释自动生成的。
godoc有两种查看文档的方式：网页方式和命令行方式 。

网页方式

想要通过网页访问go文档，最简单的方法就是访问，但是如果你不能上网（翻墙）或者想看自定义包的文档，就必须在本地建立http文档服务器。

运行如下命令启动godoc的http server

godoc -http=:6060

然后你就能通过浏览器访问127.0.0.1:6060查看go文档。

命令行方式

直接运行

godoc [package] ...

例如

godoc fmt //查看fmt包
godoc fmt Printf //查看fmt包中的Printf函数

需要注意的是，godoc默认情况下只会在GOROOT和GOPATH路径下搜索，可以使用-goroot指定搜索路径。

godoc -q 可以搜索所有"string"字符串出现的地方。
如

# godoc -q Reader


QUERY
        Reader

DID YOU MEAN

        reader

Types
    strings.Reader
    bytes.Reader
    io.Reader
    bufio.Reader
    net/textproto.Reader
    debug/dwarf.Reader
    compress/flate.Reader
    compress/gzip.Reader
    mime/multipart.Reader
    archive/zip.Reader
    image/jpeg.Reader
    archive/tar.Reader
    encoding/csv.Reader
    mime/quotedprintable.Reader

Variables
    crypto/rand.Reader

PACKAGE-LEVEL DECLARATIONS

package bufio
        /src/bufio/bufio.go:31

...

编写自己的文档

前面说过，golang会把注释自动变成文档，这就需要我们在编写代码时注意注释的写法。

对于想变成文档的注释，需要放在被注释内容的前面，且注释中间不能有空行。
对于package，注释的第一句会出现在package索引的Synopsis中。
例如：

// Copyright 2016 vv.
// This should not be shown in godoc.

// This is an example project for godoc.
package hello

godoc对应的部分

PACKAGE DOCUMENTATION

package hello
    import "github.com/vv1133/golang_example/doc/hello"

    This is an example project for godoc.

可以看到，由于第三行是空行，前面两行就没有出现在文档中。

对于程序中已知且还未修改的bug，可以使用BUG来注释，这些内容会出现在文档的结尾。
如：

// BUG(r): Dog SetAge has no effect.

对应godoc生成

BUGS

   Dog SetAge has no effect.

附：完整的代码和文档

代码

// Copyright 2016 vv.
// This should not be shown in godoc.

// This is an example project for godoc.
package hello

// Animal is the interface implemented by any
// value that has an Age() method.
type Animal interface {
// Age returns the value of animal's age.
Age() int
// SetAge sets the age of this animal.
SetAge(int)
}

// Cat infomation.
type Cat struct {
age int
}

// Dog infomation.
type Dog struct {
age int
}

func (this Cat) Age() int {
return this.age
}

func (this *Cat) SetAge(age int) {
this.age = age
}

func (this Dog) Age() int {
return this.age
}

// BUG(r): Dog SetAge has no effect.

func (this Dog) SetAge(age int) {
this.age = age
}

生成的文档

PACKAGE DOCUMENTATION

package hello
    import "github.com/vv1133/golang_example/doc/hello"

    This is an example project for godoc.

TYPES

type Animal interface {
    // Age returns the value of animal's age.
        Age() int
    // SetAge sets the age of this animal.
    SetAge(int)
}
    Animal is the interface implemented by any value that has an Age()
    method.

type Cat struct {
    // contains filtered or unexported fields
}
    Cat infomation.

func (this Cat) Age() int

func (this *Cat) SetAge(age int)

type Dog struct {
    // contains filtered or unexported fields
}
    Dog infomation.

func (this Dog) Age() int

func (this Dog) SetAge(age int)



BUGS

    Dog SetAge has no effect.