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 强大之处的介绍