本文最初发表在我的个人博客，查看原文，获得更好的阅读体验

---

一 注释

Go提供了两种风格的注释： 一种是C风格的块注释/* */，另一种是C++风格的行注释//，一般情况下使用行注释就可以了；块注释更多情况下出现在包的注释上，也可在表达式中或注掉大段代码时使用。

注释不可嵌套，也不能从符文或字符串字面量中开始。

二 go文档生成

godoc命令既是一个程序，又是一个Web服务器。它可以从源代码的注释中提取有关包内容的文档。顶级声明之前出现的注释（没有插入新行）将与声明一起被提取，作为该条目的解释性文档，而且顶级声明之前的任何注释都充当该声明的doc注释。这些注释的类型和风格决定了godoc生成的文档的质量。

每个包都需要提供包注释，即package子句之前的块注释。如果一个包下面有多个源文件，只需要在其中任意一个提供包注释即可。包注释需要从整体上对该包进行介绍，并提供包相关的信息。它将先出现在godoc页最上面，并应为后面的内容建立详细的文档。包中的每一个导出名称（首字母大写）也需要文档注释。

如果一个包的功能很简单，就不需要写很长的块注释，直接写行注释即可。

1 godoc命令

godoc命令可以在本地启动一个web服务器，让我们可以以web的方式查看go的文档，直接输入该命令默认监听本地6060端口，然后在浏览器中打开http://localhost:6060即可拥有一个跟官网几乎一样的本地站点：

当然，你也可以使用其他端口：

godoc -http=localhost:8080

该文档中同样会包含你自己的文档注释，前提是你要按照上述规范书写代码文档。

你可以执行godoc -h 或 godoc --help来查看其他可用参数。 另外-play参数可以开启playground，但似乎还是访问的外网，如果能本地就好了： 2019/05/23 17:27:53 making POST request: Post https://play.golang.org/compile: dial tcp 216.239.37.1:443: i/o timeout

或者本地运行tour尝试:

go get golang.org/x/tour tour

2 go doc子命令

另外，如果你喜欢命令行下的文档，可以使用go doc [package]来查看：

$ go doc fmt

会输出fmt包的文档：

package fmt // import "fmt" Package fmt implements formatted I/O with functions analogous to C's printf and scanf. The format 'verbs' are derived from C's but are simpler. Printing The verbs: General: %v the value in a default format when printing structs, the plus flag (%+v) adds field names %#v a Go-syntax representation of the value %T a Go-syntax representation of the type of the value %% a literal percent sign; consumes no value Boolean: %t the word true or false ... ...

go doc 可以接受一个或多个参数，不加任何参数会打印当前目录的文档。

一些选项： -c 匹配符号时保持大小写 -u 显示所有导出和未导出的符号，方法，和字段。

更多选项和用法可以查询go help doc。

三 注释格式化

注释不需要额外的格式化，如星号（*）拼成的banner。生成的注释甚至可能不以等宽字体显示，因此不要依赖于空格进行对齐，godoc会像gofmt那样处理好这些。Go的注释被当做纯文本看待，所以不像Java中可以写html标签，如果你写了，会被原样输出。唯一生效的是缩进文本，会以等宽字体显示，这点适用于代码片段。fmt包就使用了这种效果。

godoc有时可能并不格式化注释，这取决于上下文，所以确保注释够直观，例如正确的拼写，标点符号，语法结构，折叠长行等。

文档注释最好是一个完整的句子。第一句应该是一句摘要，并且以所声明的名称开头。

// Compile 解析正则表达式，如果成功， // 就返回一个可用于匹配文本的 Regexp。 func Compile(str string) (*Regexp, error) {

如果每个文档注释都以它描述的项目的名称开头,就可以方便地使用go doc和grep进行查找。

go doc -all regexp | grep -i parse

Go的声明语法中允许分组声明。单个文档注释可以介绍一组常量或变量。由于整个声明是一块出现的，这样的注释往往很笼统。

// Error codes returned by failures to parse an expression. var ( ErrInternal = errors.New("regexp: internal error") ErrUnmatchedLpar = errors.New("regexp: unmatched '('") ErrUnmatchedRpar = errors.New("regexp: unmatched ')'") ... )

分组声明还可以只是条目之间的关系，例如一组受互斥锁保护的变量。

var ( countLock sync.Mutex inputCount uint32 outputCount uint32 errorCount uint32 )

参考： https://golang.org/doc/effective_go.html#commentary