godoc 介绍以及 Golang 注释规范
Golang 的文档从一开始发布就很完善了，但是很多用法我一直也么搞明白，今天详细研究了下，整理出来。
命令
golang 官方有有文档自动生成网站，地址是 godoc.org，比如：logger 的文档，godoc也可以在本地启动：
godoc -http=:6060
启动之后浏览器访问 localhost:6060，就能看到文档首页了。如果想看自己代码的文档，后面输入包的路径即可，比如：
http://localhost:6060/pkg/github.com/mnhkahn/gogogo/
代码或者注释文档的修改可以实时更新，不需要重启服务。
代码中注释生成文档
godoc支持package、const、var和func这些代码生成文档，而且只会对public变量(首字母大写)自动生成，而private变量则不会。
Package
在自动生成的时候，比如说对于包，对包介绍的内容用的就是包名上面的注释（变量和函数同理）。如果是多个包，就会把多个包的注释放在一起，按照文件名字母顺序排序。
如果多个注释中间有一个空行，那么只会算挨着变量位置的注释，其它的会被丢弃。
包生成的内容会放到文档的「Overview」里面。举个例子：
// package gogogo
/*
A web framework includes app server, logger, panicer, util and so on.
*/
变量和函数
和包类似，常量会放到「Constants」里，变量会放到「Variables」里，后面跟的是函数。
BUG
如果代码中有 bug，可以使用注释：
BUG(who): xxx
它会被识别为一个 bug，可以在文档中的「Bugs」中看到。
Deprecated
顺便提一句，弃用注释：
// Deprecated: xxx
这个注释不会体现在godoc中，但是还是挺有用的，Goland可以识别它并作出提示。
链接 URL 自动转成 HTML 的 a 标签
// SetFlag sets log flags. For more information, see the sdk https://golang.org/pkg/log/#pkg-constants.
注释自动生成
有一个自动生成注释的工具gocmt。安装和使用：
go get -u github.com/Gnouc/gocmt
gocmt -i $FilePath$
这个命令可以结合 Goland 的「External Tools」使用，检测文件是否改动，实时生成注释。
doc.go
如果包注释超过3行，可以把注释都迁移到doc.go文件中。
多行注释自然需要支持一些复杂的格式，而godoc支持的并不是Markdown这种熟悉的格式，下面详细说明一下。
标题和段落：
先看看效果：
如果首字母是大写，并且结尾没有标点符号，是标题。结尾有标点的自然是段落了。
代码
注释中的代码也可以转成代码块。如果是通过//来注释，因为默认注释和正文中间是一个空格，那么多整一个空格（最少多一个）就会被识别为代码了。而段注释也同理，比常规注释多一个空格就行，不过我喜欢用 tab。
example_PackageName_test.go
例子非常重要，基本上项目就是通过每个包的例子搭起来的。
例子文件需要创建一个新文件，格式是example_PackageName_test.go。不加 example 的前缀也可以，不过我觉得还是加上好一些，不加感觉和单元测试文件一样。包名也有要求，是PackageName_test。在这个文件中加函数，函数名的格式是ExampleFuncName。不加函数名的话是包级别示例。加函数名的话是函数级别的示例。
包级别的例子：
func Example() {
logger.Info("hello, world.")
}
包级别的示例放在文档的开头处，而函数级别的示例放在函数后面，函数名得保持一致哦。
func ExampleNewLogger() {
w := os.Stdout
flag := log.Llongfile
l := logger.NewWriterLogger(w, flag, 3)
l.Info("hello, world")
}
最后
我们写代码都不太爱写注释，每当使用golint这些工具检测代码的时候，就会有一堆的错误提示。看了今天的文章，是不是愿意写注释了呢？
第二部分也是一个 Go 语言写注释的规范说明，大家可以参考这个。
本文涉及的代码可以从这里下载。赶紧 star 起来啊。
更多阅读：
原文链接：godoc 介绍以及 Golang 注释规范，转载请注明来源！
–EOF–