Godoc 安装与使用

笔者最近有一项开发程序包的任务需要完成，程序包设计好后还需要自动生成 API 文档，这就需要使用到 godoc 命令，由于生成的过程走过许多弯路，所以在此记录一下

命令 godoc 是一个很强大的工具，用于展示指定代码包的文档。如果我们的代码包在网上开源的话，别人使用我们的代码包，就可以通过查看 API 文档来快速了解代码包的使用方法。

本人在 Windows 和 MAC OS 环境下都进行了安装，两者略有不同，在下面分别记录：

• Windows ：直接按照我下方的命令执行，就可以在目录的 bin 文件夹生成 godoc 可执行文件

  mkdir -p $GOPATH/src/golang.org/x
  cd $GOPATH/src/golang.org/x
  git clone https://github.com/golang/tools.git
  cd tools/cmd/
  go install ...
  

• MAC OS：如果大家有翻墙软件的话，下载的方式比较简单，直接执行下面的命令：go get -v -u golang.org/x/tools/cmd/godoc，执行完毕后到 bin 文件夹中进行查看，就可以生成所要的执行文件：

  

  然后在命令行中就可以正常运行了

  如果无法翻墙的话，在国内的网络环境也可以使用以下命令：git clone https://github.com/golang/tools golang.org/x/tools，即在 GOPATH 下构建一个 golang.org/x/tools 的包，然后 go build golang.org/x/tools/cmd/godoc这样能够编译出 godoc 二进制

  然后在命令行中也可以正常执行 godoc 命令

该命令有两种模式可供选择。如果在执行命令时不加入-http标记，则该命令就以命令行模式运行。在打印纯文本格式的文档到标准输出后，命令执行就结束了。比如，我们用命令行模式查看代码包fmt的文档：

godoc fmt

读者可以自己运行一下上述命令。在该命令被执行之后，我们就可以看到编排整齐有序的文档内容了。这包括代码包fmt的综述和所有可导出成员的声明、文档以及例子。

有时候我们只是想查看某一个函数或者结构体类型的文档，那么我们可以将这个函数或者结构体的名称加入命令的最后面，像这样：

godoc fmt Printf

或者：

godoc os File

如果我们想同时查看一个代码包中的几个函数的文档，则仅需将函数或者结构体名称追加到命令后面。比如我们要查看代码包fmt中函数Printf和函数Println的文档：

godoc fmt Printf Println

如果我们不但想在文档中查看可导出成员的声明，还想看到它们的源码，那么我们可以在执行godoc命令的时候加入标记-src，比如这样：

godoc -src fmt Printf

Go语言为程序使用示例代码设立了专有的规则。我们在这里暂不讨论这个规则的细节。只需要知道正因为有了这个专有规则，使得godoc命令可以根据这些规则提取相应的示例代码并把它们加入到对应的文档中。如果我们想在查看代码包net中的结构体Listener的文档的同时查看关于它的示例代码，那么我们只需要在执行命令时加入标记-ex。使用方法如下：

godoc -ex net Listener

在实际的Go语言环境中，我们可能会遇到一个命令源码文件所产生的可执行文件与代码包重名的情况。比如本节介绍的命令go和官方代码包go。现在我们要明确的告诉godoc命令要查看可执行文件go的文档，我们需要在名称前加入“cmd/”前缀：

godoc cmd/go

另外，如果我们想查看HTML格式的文档，就需要加入标记-html。当然，这样在命令行模式下的查看效果是很差的。但是，如果仔细查看的话，可以在其中找到一些相应源码的链接地址。

一般情况下，godoc命令会去Go语言根目录和环境变量GOPATH的值（一个或多个工作区）指向的工作区目录中查找代码包。不过，我们还可以通过加入标记-goroot来制定一个Go语言根目录。这个被指定的Go语言根目录仅被用于当次命令的执行。示例如下：

godoc -goroot="/usr/local/go" fmt

现在让我们来看看另外一种模式。如果我们在执行命令时加上-http标记则会启用另一模式。这种模式被叫做Web服务器模式，它以Web页面的形式提供Go语言文档。

我们使用如下命令启动这个文档Web服务器：

godoc -http=:8080