安装及使用Godoc的过程中需要注意什么？怎么简化文档生成过程？

研发专家-道长生 • 2024年10月26日上午10:16 • 技术洞察 • 阅读 46

开发软件时，文档是确保清晰度、协作性和可维护性的关键。对于Go语言爱好者而言，Godoc是由Go社区官方提供的一款重要的工具。它通过解析嵌入在Go代码中的注释，自动生成API文档，并支持在线和本地浏览。

文章导航

一、Godoc的主要功能有哪些？

Godoc遵循特定的格式规范，确保文档结构化和易读。此外，它的这些特性使其成为开发者手中的强大工具：

自动生成文档：Godoc 可以自动从 Go 代码中提取文档信息。
在线浏览：支持在线查看文档，方便团队协作和外部访问。
本地浏览：可以在本地环境中查看文档，便于离线开发。
搜索功能：提供了强大的搜索功能，方便查找相关 API 和包信息。
注释规范：Godoc 支持特定格式的注释，使得文档更加规范和易读。

二、如何安装和使用Godoc？

根据不同的Go版本，Godoc的安装和使用过程可能略有不同。

安装

Go 1.5之前godoc是一个内置的命令，无需单独安装，新版本的Go不再自带这个命令，需要单独安装。

# 创建 GOPATH 目录结构
mkdir -p $GOPATH/src/golang.org/x

# 切换到创建的目录
cd $GOPATH/src/golang.org/x

# 克隆 golang/tools 仓库
git clone https://github.com/golang/tools.git

# 切换到 tools/cmd 目录
cd tools/cmd/

# 安装所有子命令
go install ./...

也可以直接：

   # 找个项目执行 默认是安装到GOBIN 环境变量定义的目录中
   go get golang.org/x/tools/cmd/godoc
   # 然后去对应目录下找即可

使用

启动 Godoc 服务器：

// 默认端口是6060
godoc -http=:6060

访问http://localhost:6060即可查看文档。

该方式读取的是本地$/usr/local/go/src目录下的文档，通常是go本身的库。

本地项目文档

本地项目引入

例：https://github.com/fengzhiyuqiao/student

像上述项目在本地时，需要按src/github.com/fengzhiyuqiao/student

（原因：为了适配godoc文档的跳转功能，它是安装文件引用包的路径去访问，故安装相应的存储路径存放就可以正常跳转）

方式存放，其中src是godoc读取的默认目录，后续按仓库地址路径存放

 //  -goroot指定读取目录，-index 开启索引（开启后才能搜索）
 godoc -http=:6061 -goroot=/home/feng/worker -play  -index=true

注：不要使用软连接等方式，使用该方式，可以查看文档，但无法搜索

使用搜索功能

三、Godoc注释编写的写法是什么

关于注释的写法及在godoc解析后的样式，可参考官方文档 Go Doc Comments以及sync包的文档

注释不可与目标隔一行，不然是不会显示出来的。

以下可供参考：

结构体

// Student 学生结构体 注释不可与目标隔一行
type Student struct {
    // Name is student name
    Name string `json:"name"`
    // Age 学生年纪
    Age int `json:"age"`
    // Score 学生成绩
    Score map[string]int `json:"score"`
}

函数

// New 功能: 创建一个学生
//
//  参  数:
//         name   : 学生名字
//         age       : 学生年纪
//  返回值:
//         *Student   : 学生指针
func New(name string, age int) *Student {
    return &Student{
       Name: name,
       Age:  age,
    }
}