如何维护一个自己的 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 服务的方式。