Godoc 安装与使用

谁践踏了优雅 2022-08-30 11:38 398阅读 0赞

### 文章目录 ###

*   *   *  前言
         *  Godoc 简介
         *  安装过程
         *  GoDoc 使用说明

### 前言 ###

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

> 博主注：学习go语法的同时为了方便查看对应的文档，我们需要安装godoc，go在1.13之前是自带godoc的，之后的版本需要自行安装，本人最近学习使用的版本是1.14.12

### Godoc 简介 ###

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

### 安装过程 ###

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

> 博主注：如果能正常下载Go包，可以直接使用go get godoc安装

`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 ...

> 博主注：如果此处遇到了无法下载包的问题，可以参考https://blog.csdn.net/sdujava2011/article/details/118909472?spm=1001.2014.3001.5501进行解决

`MAC OS`：如果大家有翻墙软件的话，下载的方式比较简单，直接执行下面的命令：`go get -v -u golang.org/x/tools/cmd/godoc`，执行完毕后到 `bin` 文件夹中进行查看，就可以生成所要的执行文件：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NkdWphdmEyMDEx_size_16_color_FFFFFF_t_70]  
然后在命令行中就可以正常运行了

如果无法翻墙的话，在国内的网络环境也可以使用以下命令：`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 命令

安装完成后，打开你的`$GOPATH/bin`目录，里面有godoc.exe证明安装成功！

### 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

标记`-http`的值`:8080`表示启动的Web服务器使用本机的8080端口。之后，我们就可以通过在网络浏览器的地址栏中输入http://localhost:8080来查看以网页方式展现的Go文档了。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NkdWphdmEyMDEx_size_16_color_FFFFFF_t_70 1]  
生成线下 html 文件的具体方法为：

首先执行命令 `go doc`(注意需要有空格)  
然后执行以下命令 `godoc -url="pkg/代码包的路径(import 后面的路径)" > 生成的文件名.html`，即可生成所需要的 html 文件，虽然这样比较方便，但是打开的 html 文件并没有网页版浏览的方便.

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NkdWphdmEyMDEx_size_16_color_FFFFFF_t_70]: /images/20220829/ea0f0c8d7c6d42a18246365158f506d6.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3NkdWphdmEyMDEx_size_16_color_FFFFFF_t_70 1]: /images/20220829/86874719381b49bfb124e6d3346edad9.png