命令

godoc

启动之后浏览器访问 localhost:6060，就能看到文档首页了。如果想看自己代码的文档，后面输入包的路径即可，比如：

代码或者注释文档的修改可以实时更新，不需要重启服务。

代码中注释生成文档

godocpackageconstvarfuncpublicprivate

Package

在自动生成的时候，比如说对于包，对包介绍的内容用的就是包名上面的注释（变量和函数同理）。如果是多个包，就会把多个包的注释放在一起，按照文件名字母顺序排序。

如果多个注释中间有一个空行，那么只会算挨着变量位置的注释，其它的会被丢弃。

包生成的内容会放到文档的「Overview」里面。举个例子：

变量和函数

和包类似，常量会放到「Constants」里，变量会放到「Variables」里，后面跟的是函数。

BUG

如果代码中有 bug，可以使用注释：

它会被识别为一个 bug，可以在文档中的「Bugs」中看到。

Deprecated

顺便提一句，弃用注释：

godoc

链接 URL 自动转成 HTML 的 a 标签

注释自动生成

有一个自动生成注释的工具gocmt。安装和使用：

这个命令可以结合 Goland 的「External Tools」使用，检测文件是否改动，实时生成注释。

doc.go

如果包注释超过3行，可以把注释都迁移到doc.go文件中。

godocMarkdown

标题和段落：

先看看效果：

如果首字母是大写，并且结尾没有标点符号，是标题。结尾有标点的自然是段落了。

代码

//

example_PackageName_test.go

例子非常重要，基本上项目就是通过每个包的例子搭起来的。

example_PackageName_test.goPackageName_testExampleFuncName

包级别的例子：

包级别的示例放在文档的开头处，而函数级别的示例放在函数后面，函数名得保持一致哦。

最后

golint

第二部分也是一个 Go 语言写注释的规范说明，大家可以参考这个。

本文涉及的代码可以从这里下载。赶紧 star 起来啊。

更多阅读：