文档章节

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

鼎铭
 鼎铭
发布于 01/16 00:02
字数 922
阅读 273
收藏 9

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

© 著作权归作者所有

共有 人打赏支持
鼎铭
粉丝 49
博文 70
码字总数 44459
作品 0
东城
程序员
私信 提问
Zan-Group/zanphp

基于 PHP 协程的网络服务框架,提供最简单的方式开发面向 C10K+ 的高并发SOA服务和RPC服务。 每天为2,000+个服务提供300,000,000+次访问量支持,广泛应用于有赞各项业务。 核心特性 基于 实现...

Zan-Group
2017/06/21
0
0
PHP网络服务框架--zan

Zan PHP Framework Zan PHP是基于PHP协程的网络服务框架,提供最简单的方式开发面向C10K+的高并发HTTP服务或SOA服务。 核心特效 基于 yield 实现了独立堆栈的协程 类似于 Golang 的并发编程模...

demon666
2016/07/21
1K
0
基于Golang的IP地址信息查询服务

https://github.com/miraclesu/ipip 工作中经常会有通过IP匹配用户信息的需求,如确定用户所在的地区(国家/省份/城市)、运营商、时区、经纬度等等。前一阵有个Golang开发的项目也有这样的需...

mickelfeng
2017/11/22
0
0
golang 入门

golang http://golang.org/ Go语言是由Google开发的一个开源项目,具体语言特征就不细说了,可以查看一下文档。 学习使用了几天,想起了一句广告语: 简约而不简单。 资深程序员 云风对go语言...

xsong
2011/12/19
2.4K
1
使用SWIG桥接Golang和Windows DLL

最近看了下Go语言,利用Dynamsoft Barcode SDK做了一个简单的Golang条形码扫描。这里分享下如何使用SWIG来快速封装底层C/C++接口。 参考原文:How to Use SWIG to Link Windows DLL with Go...

yushulx
2015/11/24
273
0

没有更多内容

加载失败,请刷新页面

加载更多

12_第一个Flutter程序

使用 package 在这一步中,你将开始使用一个名为 english_words 的开源软件包,其中包含数千个最常用的英文单词以及一些实用功能。 你可以 在 pub.dartlang.org 上找到 english_words 软件包...

口十耳
14分钟前
0
0
指明方向与趋势!2019开发者技能报告出炉!!!

近日国外开发者平台 HankerRank 发布了 2019 年开发者技能调查报告( https://research.hackerrank.com/developer-skills/2019 ),该报告根据对71,281开发者的调查得出。 2018 年最受欢迎的...

阿里云官方博客
16分钟前
0
0
【Maven冷知识】Compiler插件

很多同学在pom的配置中都喜欢加上这样一段配置信息: 从配置信息上看,这是maven对Java源代码进行的编译配置,采用了Java 7 进行编译,但是为什么要加上这段配置呢?不加有没有什么影响?很多...

算法与编程之美
19分钟前
0
0
磊哥测评之数据库SaaS篇:腾讯云控制台、DMC和小程序

本文由云+社区发表 作者:腾讯云数据库 随着云计算和数据库技术的发展,数据库正在变得越来越强大。数据库的性能如处理速度、对高并发的支持在节节攀升,同时分布式、实时的数据分析、兼容主...

腾讯云加社区
21分钟前
0
0
Visual Studio系列教程:使用XAML工具创建用户界面(二)

Visual Studio是一款完备的工具和服务,可帮助您为Microsoft平台和其他平台创建各种各样的应用程序。在本系列教程中将介绍如何为图像编辑创建基本的用户界面,有任何建议或提示请在下方评论区...

ymy_666666
23分钟前
0
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部