如果你想查询包、函数等的说明,可以使用go doc
指令。
查询文件
如果你想要查询包的文件说明,可以使用go doc packageName
,例如go doc fmt
可查询fmt
包的说明,

可以看到,这显示了整个包的说明,通常我们会想要查询包中某个函数,这可以使用go doc packageName.funcName
,例如,查询fmt
中的Println
,可以使用go doc fmt.Println
:

你也可以加上-src
来查询源码,虽然整个包也可以查询,不过我想,这直接开 Go 目录的 src 中源码来看比较快,或许加上-src
的机会,会是在查询函数的源码时比较多:

如同go xxx
的指令说明,想要得到go doc
的说明,可以使用go help doc
指令。

注解即文件
实际上,go doc
的文件说明来自于源码中的注解,这样的概念有点类似 Java 的 JavaDoc,或者是 Python 的 DocString,不过 Go 的理念是让它更简单,不使用特殊标记,不使用特别的格式,希望可以在没有go doc
的场合中,也可以借由阅读源码中的注解,轻易地得到文件说明。
当然,基本上还是要有一些约定,例如,在函数之前,紧接着函数的注解,中间没有空白行,就是函数的文件说明来源。
类似地,在包之前,紧接着包的注解,就是包的文件说明来源,通常,一个包的文件说明,会是来自于包中,一个 doc.go 中package
定义前的注解,例如,你可以在fmt
的源码目录中,找到一个doc.go,其中除了package fmt
之外,没有任何源码,剩下的只有注解。
除了函数、包之外,最顶层的类型定义、变量、常数等前紧接着的注解,都可以是文件的来源,不相邻的注解则会被godoc
忽略,如果有已知的 Bug,可以使用BUG()
标示,例如bytes.go中有个:
// BUG(rsc): The rule Title uses for word boundaries does not handle Unicode punctuation properly.
func Title(s []byte) []byte {
....
这会出现在文件的Bugs 区域。
如果你想要从注解产生 HTML 文件(使用-html
实参),那么有几个简单的规则(用过 Markdown 的应该感觉有点熟悉),参考一下 Go 的源码,应该能很快地掌握。
基本上,go doc
会在GOROOT
与GOPATH
中的源码查询注解作为文件,如果想改变查询时的 Go 目录,可以使用-goroot
指定。
有关注解与文件间的关系,也可以进一步参考Effective Go 的 Commentary。
godoc 文件服务器
Go 1.2rc1 之后,曾经从go doc
改用godoc
指令了,不过,从Go 1.5 Release Notes中看到,Go 1.5 有个新的go doc
指令,专门用于命令行模式下的文件查询,这使得godoc
主要剩下文件服务器的功能,因而在 Go 1.13 中,godoc
被移除。
如果在一个网络受限的环境,又想要在网页上查询文件,还是可以安装godoc
:
go get -u golang.org/x/tools/cmd/godoc
这时执行 bin 中的godoc
,并附带一个-http
实参指定端口,例如,./bin/godoc -http=:6060
,这会在本机启动一个 HTTP 服务器,使用浏览器连接 http://localhost:6060(或 http://主机IP:6060)就可以查询文件:
