如何维护一个自己的 golang doc 服务
本文内容是如何维护一个golang 在线的doc 服务。
1 什么是godoc ?
godoc 是 golang 官方提供的文档生成工具，
2 为什么要有godoc ？
我们经常遇到一个问题，就是代码和文档不一致，线上代码版本总和wiki 给的不一样，让人吐槽。为了解决这个痛点问题，golang 给出了个官方方案，也就是，文档应该与代码一起，当更新代码的时候，文档也能够同步得到更新。对于程序员来说，代码发布后，我们文档自动同步更新，这样非常完美。这就是为什么要有 godoc。
3 怎么写godoc ？
godoc 支持 package、const、var和 func 这些类型根据注释生成文档，而且只会对公有变量(首字母大写)生成。我们可以直接通过doc 查具体函数签名，函数使用说明，还有example 示例代码。
3.1 package, type, const, func
type, const, func以名称为注释的开头, package以Package name为注释的开头, 其中有效的关键字注释不应该超过3行。
// Package AAA ...
package AAA
// Xyz ...
const Xyz = 1
// Abc ...
type Abc struct {}
// Bcd ...
func Bcd() {}
3.2 Bug
以BUG(who)开头的注释, 将被识别为已知bug, 显示在bugs区域
// BUG(who): 我是bug说明
// Package AAA ...
package AAA
3.3 Deprecated
函数签名前加// Deprecated: xxx ，使用时，ide 一般会自动提醒。不会加到doc 中
3.4 example
test 有两种，一种是单测，一种是example, 也就是示例代码。example 的代码和注释 使用godoc 会自动加到doc 中去。example 的示例如下：
// 文件必须放在 AAA包目录下, 名字必须为example_xxx_test.go
// Package AAA_test 为AAA example 示例
package banana_test
// 不加函数名，是包级别示例，放最上面
func Example() {
fmt.Println("Hello World")
// Output:
// Hello World
}
// 函数A将被展示在Function区域
func ExampleA() {
fmt.Println("Hello A")
// Output:
// Hello A
}
4 如果搭建自己的doc 服务
4.1 使用 godoc
godoc 本身能够 提供一个简单的httpserver 展示doc
godoc -http=:6060
使用效果如图:
通过 godoc 可以查看本机GOPATH 下所有pkg 的文档，因为是本地，反应速度很快。如果公司需要维护一个doc 服务，可以考虑定时同步或者gitlib添加钩子，将代码库代码代码到一台机器上去，在这个机器上起godoc 服务。
4.2 使用官方的 godoc.org 源码
官方有个网站，提供在线doc 查询：https://godoc.org/ 。这个网站比较好用，可以查询github 和公有库代码的doc，代码开源。 使用方式如下：
1，install redis
2，install Cloud SDK at https://cloud.google.com/sdk/docs/ ，为了search 的时候走代理
3，clone
```
git clone https://go.googlesource.com/gddo $GOPATH/src/github.com/golang/gddo
```
4，Run the server:
```
cd $GOPATH/src/github.com/golang/gddo/gddo-server && \
go build && \
GITHUB_TOKEN=xyzzy123 ./gddo-server
```
5, http://127.0.0.1:8080
公司自己维护自己的gitlab的话，本身也可以支持，当搜索pkg ，会去clone 到临时文件夹，然后生成doc 数据放redis 中，反应速度还是挺快的。值得注意的是，这个库本身会每天定时去源站同步代码，所有不需要像第一种一样，得异步回调或者定时同步。
最后
本文总结了使用golang 写文档的标准做法，然后给出了两种维护doc 服务的方式。
