以下内容来自腾讯后台研发工程师andru

刚入门 Go 开发时，在开源项目的主页上我们经常可以看到这样的一个徽章：

https://pkg.go.dev/pkg.go.dev
pkg.go.devGoDocpkg.go.dev
godoc

什么是 GoDoc

godoc
https://godoc.orggodoc.orgpkg.go.devpkg.go.devgodocgodocpkg.go.devpkgsitepkgsiteGoDoc

目前的 godoc 和 pkgsite 有两个作用，一个是用来本地调试自己的 GoDoc 显示效果；另一个是在无法科学上网的时候，用来本地搭建 GoDoc 服务器之用。

godoc 命令

godoc

godc 命令有多种模式和参数，这里我们列出最常用和最简便的模式：

github.com/Andrew-M-C/go.jsonvaluehttp://${IP}:${PORT}/pkg/github.com/Andrew-M-C/go.jsonvalue/

pkgsite 命令

pkg.go.devpkgsite
pkgsitepkgsite

然后和 godoc 类似:

jsonvaluepkg/http://${IP}:${PORT}/github.com/Andrew-M-C/go.jsonvalue/

pkg.go.dev 内容

总体内容

pkg.go.dev
module
pkgsite

Documentation

让我们点开 Documentation，一个完整的 package，可能包含以下这些内容:

pkg.go.devgodocpkgsite

下面我们具体来说明一下 GoDoc 的语法。

GoDoc 语法

pkg.go.dev
///* ... *///command//* */

绑定 GoDoc 与指定类型

对于任意一个可导出内容，紧跟着代码定义上方一行的注释，都会被视为该内容的 GoDoc，从而被提取出来。比如说：

pkgsite
SomeTypeA// SomeTypeA

换行（段落）

pkgsite

实际上，在注释中如果只是单纯的一个换行另写注释的话，在页面是不会将其当作新的一段来看待的，GoDoc 的逻辑，也仅仅渲染完这一行之后，再加一个空格，然后继续渲染下一行。

如果要在同一个注释块中新加一个段落，那么我们需要插入一行空注释，如下:

内嵌代码

如果有需要的话，我们可以在注释中内嵌一小段代码，代码会被独立为一个段落，并且使用等宽字符展示。比如下面的一个例子:

总结一下：在注释块中，如果部分注释行符合以下标准之一，则视为代码块:

\t

普通注释和代码块之间可以不用专门的空注释行，但个人建议还是加上比较好。

Overview 部分

package xxx// Package xxx

如果在一个 package 中，有多个文件都包含了包注释，那么 GoDoc 会按照文件的字典序，依次展示这些文件中的包注释。但这样可能会带来混乱，因此一个 package 我们应当只在一个文件中写包注释。

一般而言，我们可以选择以下的文件写包注释：

弃用代码声明

vX.Y.ZDeprecated:
pkgsite

此外，在正文中，也会刻意用灰色字体低调展示，并且隐藏注释正文，需要点开才能显示:

代码示例文档

At()

那么，文档中的代码示例又应该如何写呢？

package包名_test
go test

示例代码的声明

At()

这个函数命名有几个部分：

// Output:
Opt

甚至连示例说明都没有。

godocAt()

在官网上发布 GoDoc

好了，当你写好了自己的 GoDoc 之后，总不是自己看自己自娱自乐吧，总归是要发布出来给大家看的。

https://pkg.go.dev/${package路径名}jsonvaluegithub.com/Andrew-M-C/go.jsonvaluehttps://pkg.go.dev/github.com/Andrew-M-C/go.jsonvalue
pkg.go.devpkg.go.dev
GoDocpkg.go.dev
htmlmarkdown

参考资料


欢迎点赞分享，关注@鹅厂架构师，一起探索更多业界领先产品技术。