如何维护一个自己的 golang doc 服务

原创
2019/01/16 00:02
阅读数 3.6K

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

展开阅读全文
加载中
点击引领话题📣 发布并加入讨论🔥
打赏
0 评论
10 收藏
0
分享
返回顶部
顶部