Go语言doc

1、Go语言doc

go doc 命令可以打印附于 Go 语言程序实体上的文档，我们可以通过把程序实体的标识符作为该命令的参数来

达到查看其文档的目的。

所谓Go语言的程序实体，是指变量、常量、函数、结构体以及接口，而程序实体的标识符即是代表它们的名称。

标识符又分非限定标识符和限定标识符，其中，限定标识符一般用于表示某个代码包中的程序实体或者某个结构体

类型中的方法或字段。

下面说明怎样使用 go doc 命令，先来看一下 go doc 命令可接受的标记。

标记名称	标记描述
-c	加入此标记后会使 go doc 命令区分参数中字母的大小写，默认情况下，命令是大小写不敏感的。
-cmd	加入此标记后会使 go doc 命令同时打印出 main 包中的可导出的程序实体(其名称的首字母大写)的文档。默认情况下，这部分文档是不会被打印出来的。
-u	加入此标记后会使 go doc 命令同时打印出不可导出的程序实体(其名称的首字母小写)的文档。默认情况下，这部分文档是不会被打印出来的。

这几个标记的意图都非常简单和明确，大家可以根据实际情况选用。

go doc 命令可以后跟一个或两个参数。当然，我们也可以不附加任务参数。如果不附加参数，那么 go doc 命

令会试图打印出当前目录所代表的代码包的文档及其中的包级程序实体的列表。

// go-doc/loadgen/loadgen.go
package loadgen

import (
	"fmt"
)

// 定义接口
type Phone interface {
	call()
	call2()
}

// 定义结构体
type Phone1 struct {
	id            int
	name          string
	category_id   int
	category_name string
}

// 第一个类的第一个回调函数
func (test Phone1) call() {
	fmt.Println("这是第一个类的第一个接口回调函数,结构体数据:", Phone1{id: 1, name: "浅笑"})
}

// 第一个类的第二个回调函数
func (test Phone1) call2() {
	fmt.Println("这是一个类的第二个接口回调函数,结构体数据:", Phone1{id: 1, name: "浅笑", category_id: 4, category_name: "分类名称"})
}

// 第二个结构体
type Phone2 struct {
	member_id       int
	member_balance  float32
	member_sex      bool
	member_nickname string
}

// 第二个类的第一个回调函数
func (test2 Phone2) call() {
	fmt.Println("这是第二个类的第一个接口回调函数call", Phone2{member_id: 22, member_balance: 15.23, member_sex: false, member_nickname: "浅笑18"})
}

// 第二个类的第二个回调函数
func (test2 Phone2) call2() {
	fmt.Println("这是第二个类的第二个接口回调函数call2", Phone2{member_id: 44, member_balance: 100, member_sex: true, member_nickname: "陈超"})
}

例如，我要在 go-doc 项目的 loadgen 代码包所在目录中运行 go doc命令的话，那么就会是这样：

# loadgen目录下执行
# 程序输出
$ go doc
package loadgen // import "proj/loadgen"

type Phone interface{ ... }
type Phone1 struct{ ... }
type Phone2 struct{ ... }

如果你需要指定代码包或程序实体，那么就需要在 go doc 命令后附上参数了。例如，只要我本地的 go-doc 项目

的所在目录存在于GOPATH环境变量中，我就可以在任意目录中敲入 go doc loadgen。如此得到的输出一定是与

上面那个示例一致的。

# go-doc目录下执行
# 程序输出
$ go doc loadgen
package loadgen // import "proj/loadgen"

type Phone interface{ ... }
type Phone1 struct{ ... }
type Phone2 struct{ ... }

该代码包中的函数 call、call2 是不可导出，但是我们只需附加 -u 标记便可查看它的文档了：

# go-doc目录下执行
$ go doc -u loadgen.call
package loadgen // import "proj/loadgen"

func (test Phone1) call()
    第一个类的第一个回调函数

func (test2 Phone2) call()
    第二个类的第一个回调函数

下面再进一步，如果你只想查看 loadgen.Phone1 类型的 call 方法的文档，那么只要续写这个限定标识符就可以

了，像这样：

# go-doc目录下执行
$ go doc -u loadgen.Phone1.call
package loadgen // import "proj/loadgen"

func (test Phone1) call()
    第一个类的第一个回调函数

注意，结构体类型中的字段的文档是无法被单独打印的。另外，go doc 命令根据参数查找代码包或程序实体的顺

序是：先Go语言根目录（即GOROOT所环境变量指定的那个目录）后工作区目录（即GOPATH环境变量包含的那

些目录）。并且，在前者或后者中，go doc 命令的查找顺序遵循字典序。因此，如果某个工作区目录中的代码包

与标准库中的包重名了，那么它是无法被打印出来的。go doc 命令只会打印出第一个匹配的代码包或程序实体的

文档。

go doc 命令还可以接受两个参数，这是一种更加精细的指定代码包或程序实体的方式。一个显著的区别是，如果

你想打印标准库代码包 net/http 中的结构体类型 Request 的文档，那么可以这样敲入 go doc 命令：

$ go doc http.Request

当你指定两个参数时，作为第一个参数的代码包名称必须是完整的导入路径，即：在敲入命令go doc net/http

Request后，你会得到想要的结果。

$ go doc net/http Request

最后，在给定两个参数时，go doc 会打印出所有匹配的文档，而不是像给定一个参数时那样只打印出第一个匹配

的文档。这对于查找只有大小写不同的多个方法（如 New 和 new）的文档来说非常有用。

其它的使用：

$ go doc fmt
$ go doc fmt Printf
$ go doc os File
# 如果我们不但想在文档中查看可导出的程序实体的声明,还想看到它们的源码,那么我们可以在执行godoc命令的时候加入标记-src
$ go doc -src fmt Printf
# 在实际的Go语言环境中,我们可能会遇到一个命令源码文件所产生的可执行文件与代码包重名的情况。比如,这里介绍的标准命令go和官方代码包go。现在我们要明确的告诉godoc命令要查看可执行文件go的文档,我们需要在名称前加入cmd/前缀。
$ go doc cmd/go

2、godoc

godoc 在 go1.1.13 版本后已从核心包中移除，如果仅仅是看某个API，可以直接用 go doc。

godoc 安装：

$ go install golang.org/x/tools/cmd/godoc@latest

godoc 的使用：

$ godoc --help
usage: godoc -http=localhost:6060
  -goroot string
        Go root directory (default "D:\\OwnerSoftwareInstall\\Go")
  -http string
        HTTP service address (default "localhost:6060")
  -index
        enable search index
  -index_files string
        glob pattern specifying index files; if not empty, the index is read from these files in sorted order
  -index_interval duration
        interval of indexing; 0 for default (5m), negative to only index once at startup
  -index_throttle float
        index throttle value; 0.0 = no time allocated, 1.0 = full throttle (default 0.75)
  -links
        link identifiers to their declarations (default true)
  -maxresults int
        maximum number of full text search results shown (default 10000)
  -notes string
        regular expression matching note markers to show (default "BUG")
  -play
        enable playground
  -templates string
        load templates/JS/CSS from disk in this directory
  -timestamps
        show timestamps with directory listings
  -url string
        print HTML for named URL
  -v    verbose mode
  -write_index
        write index to a file; the file name must be specified with -index_files
  -zip string
        zip file providing the file system to serve; disabled if empty

启动执行：

# go-doc目录下执行
$ godoc -http=:6060

访问网址：

http://localhost:6060

开启搜索索引：

# 要使用-index标记开启搜索索引
# 在启动的时候添加-index参数
$ godoc -http=:6060 -index

全文本搜索结果显示条目的最大数量可以通过标记 -maxresults 提供，标记 -maxresults 默认值是10000。如果

不想提供如此多的结果条目，可以设置小一些的值。甚至，如果不想提供全文本搜索结果，可以将标记

-maxresults 的值设置为0。

因为在使用了 -index 标记的情况下文档服务器会在启动时创建索引，所以在文档服务器启动之后还不能立即提供

搜索服务，需要稍等片刻。在索引为被创建完毕之前，我们的搜索操作都会得到提示信息：

Indexing in progress: result may be inaccurate

我们演示搜索 printf：

如果我们想要访问自己本地代码生成的文档，可以使用 -goroot 参数：

$ godoc -goroot="......\go_lang_workspace" -http=:6060

访问：

也可以生成线下 html 文件，的具体方法为：

$ godoc -url "http://localhost:6060/pkg/" > doc.html

3、在线文档

在线文档地址：https://pkg.go.dev/