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