如何維護一個本身的 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 服務的方式。