Golang 见证 godoc 的强大（生成API文档，打印文档）

Golang 见证 godoc 的强大（生成API文档，打印文档）

本次我们使用的是 godoc 来生成 API 文档

一、godoc 介绍

• 在辛苦写完一个项目后，你是否苦恼于不知怎么给用户解释它的功能，又或者是觉得一一解释太过繁琐？不怕，接下来笔者要介绍的 godoc 就是一项有力的自动生成 API 工具，既方便了读者，又帮助了开发者
• godoc 是 Go 语言中一个可以自动生成 API 文档的第三方库
  
  

二、godoc 安装

① 系统环境

• 操作系统：CentOS Linux release 7.9.2009
• 代码编辑器：visual studio code
• 编译工具：go version go1.13.1 linux/amd64

② 下载安装

git clone https://github.com/golang/tools $GOPATH/src/golang.org/x/tools
go build golang.org/x/tools

• 然后在命令行中就可以正常执行 godoc 命令
• 或者也可以直接使用指令 go get -v golang.org/x/tools/cmd/godoc 一步到位

三、godoc 使用

下文将以笔者开发的 json_Marshal 项目为例，演示如何用 godoc 生成 API 文档

• 首先注释项目 iniReader main.go 文件的 main 函数，将 package 改为iniReader，然后执行如下指令:

go install
// 生成 API 文档
godoc
// 下载保存 API 文档
godoc -url="pkg/jsonmarshal/jsonmarshal" > API.html

便会在当前目录下生成 API.html 文件:

API 文档，用浏览器打开后界面如下

• 可以保存为 PDF 文件
• 或者也可以通过网络浏览器的地址栏中输入 http://localhost:8080/pkg/jsonmarshal/jsonmarshal 来查看以网页方式展现的 API 文档
  
  

四、godoc 的其他功能

• godoc 还有另一种功能就是打印纯文本格式的文档到标准输出
• 比如我们用命令行模式查看代码包 log 的文档，如下图，包括了 log 的介绍，和所有函数

go doc log

• 如果我们想查看某一个函数或结构体的文档，可以将这个函数或结构体的名称加入命令的后面，即

go doc log Fatal

• 或者

go doc log Logger

• 此外，还可以通过添加 -src 查看它们的源码

go doc -src log Fatal

以上就是 godoc 强大之处的介绍