go doc 文件即注解


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

查询文件

如果你想要查询包的文件说明,可以使用go doc packageName,例如go doc fmt可查询fmt包的说明,

go doc

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

go doc

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

go doc

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

go 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会在GOROOTGOPATH中的源码查询注解作为文件,如果想改变查询时的 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)就可以查询文件:

godoc


展开阅读全文