Golang 开发者应该都使用过 go 文档工具，但是可能大部分开发者都没有深入了解或研究过 go 文档工具，go 文档官网是 https://pkg.go.dev/ ，收录了非常多开源项目的文档，看起来专业又漂亮。

什么是 go 文档

go 文档就是 go 项目的说明文档，根据注释自动生成。2019.11 月之前，官网是 https://godoc.org ，对应的命令行工具是 godoc ，现在官网是 pkg.go.dev，对应的命令行工具是 pkgsite，godoc.org 现在已经下线并且被重定向到了 pkg.go.dev 。godoc 和 pkgsite 可以用来本地调试自己的 go 项目文档显示效果，也可以在本地查看go语言本身的文档。

pkg.go.dev 上的文档是如何出现的

你是不是非常好奇开源项目文档是怎么出现在 pkg.go.dev 上的呢？你是不是首先会想到是需要开发者上传并且需要官方审核的呢？然而并不是。

pkg.go.dev 上的文档，都是是自动地从开源项目代码中爬取并且格式化之后展现出来的。每个人都可以写自己的 go 文档并且展示在 pkg.go.dev 上，只需要遵从 go 文档的格式标准要求的注释写法写好注释即可。

pkgsite 命令行工具的使用方法

因为官方已经使用 pkgsite 取代了 godoc，本文只介绍 pkgsite 的使用方法（godoc的使用方法基本一样）。

pkgsite 可以提取项目代码注释并生成对应文档，它作为一个web服务器运行，并以网页的形式显示文档。可以使用如下命令安装最新版本的 pkgsite ，会要求升级到最新版的 golang。所以如果你的 golang 不是最新版，可以升级到最新版或者拉取 pkgsite 的代码，自己编译出对应 goalng 版本的二进制文件

go install golang.org/x/pkgsite/cmd/pkgsite@latest

安装完成后，运行 pkgsite 服务

pkgsite -http=:6060

默认情况下，pkgsite 可以查看到通过$GOROOT和$GOPATH(如果设置了)找到的包。可以通过提供一个 -goroot 参数来指定 GOROOT 路径。

更多使用方法可以参考

pkgsite --help

Go 文档对应的注释规范

项目中所有 package 里可导出的类型都会在 pkgsite 中展示出来，即便某个可导出类型没有任何注释（所有的可导出内容都应该写好注释）。如果让生成的文档看起来既专业又漂亮，需要遵循如下的注释规范：

1、Go 支持 // 和 /* ... */ 两种模式的注释符。大部分情况下推荐使用 //，出现在一行代码中间的注释或者需要大段注释的场景才推荐使用 /* ... */，例如

cst := newClientServerTest(t, h1Mode /* the test is protocol-agnostic */, th, optWithServerLog(srvLog))

2、对于任意可导出内容，建议都添加注释，代码注释的第一个单词应该是被注释的内容本身。例如

// contextKey is a value for use with context.WithValue. It's used as// a pointer so it fits in an interface{} without allocation.type contextKey struct {   name string}

3、如果想在 pkgsite 页面展示中换行的话，添加一行空注释即可，如下:

// contextKey is a value for use with context.WithValue. It's used as、//// a pointer so it fits in an interface{} without allocation.type contextKey struct {   name string}

4、如果有需要的话，可以在注释中内嵌一段代码，这段代码会在 pkgsite 中以代码块的形式展示。注释行需要以制表符 \t 开头或者多于一个空格开头，如下：

// contextKey is a value for use with context.WithValue. It's used as、//     //     ck := contextKey{"xiaoming"}//// a pointer so it fits in an interface{} without allocation.type contextKey struct {   name string}

5、文档中的 Overview 部分是对整个 package 的说明，也就是包的注释。包注释要写在 go 文件 package xxx 上面并且以 // Package xxx 开头。如果一个包中有多个文件都包含了包注释，pkgsite 会按照文件的字典顺序序依次展示这些文件中的包注释。不建议多个文件里都写包注释，建议在一个包里只在一个文件中写包注释。写包注释要遵循如下原则：

• 一般一个包里面会有一个与包名同名的文件，统一在这个文件里写包注释；
• 如果没有与包名同名的文件或者同名文件本身包含了很多代码又或者包注释比较长，可以新建一个名称为 doc.go 的文件专门用来写包注释；
• 注释以 // Package xxx 开头并且写在包名声明上面。

6、随着代码的迭代，有些方法不再推荐使用。针对这种情况，go 提供了一个关键字 Deprecated:，作为整个注释块的第一个单词即可。

// Deprecated: Use the runtime/pprof packagefunc CPUProfile() []byte {	panic("CPUProfile no longer available")}

针对 deprecated 的内容，pkgsite 不但会在目录中标识出来，也会在正文中用灰色字体展示并且隐藏注释正文。

7、代码示例文档，应当至少新建一个文件专门用来放示例代码。一般是新建一个名称为 example_test.go 的文件，包名命名为 包名_test，示例代码文件里面的方法固定以 Example 开头。

8、在 pkg.go.dev 查看文档效果。将最新代码 push 到 github 上后，就可以在浏览器中输入 https://pkg.go.dev/${package路径名} 查看文档。例如查看 gin 框架的文档在浏览访问一下地址即可：

https://pkg.go.dev/github.com/gin-gonic/gin

可以根据 tag 版本查看对应文档。

到此，是不是发现自己以前注释写的太随意了呢？