关于golang如何生成文档

go语言自带的文档生成十分好用

下面我们来看看具体怎么操作

我们先来看一个没有任何注释的一个先进先出的队列例子

package queue

type Queue []interface{}

func (p *Queue) Push(v interface{}){
	*p = append(*p,v.(int))
}
func (p *Queue) Pop() interface{}{
	head := (*p)[0]
	*p = (*p)[1:]
	return head
}
func (p *Queue) IsEmpty() bool{
	return len(*p) == 0
}

接下来我们打开powershell（cmd或者linux，mac都可以）输入go doc

这样我们就打开了系统自带的文档一般情况下我们都是使用ide查看文档这个只是作为了解使用

不过命令行有一个godoc -http :6060非常好用我们可以使用 godoc -help打开godoc帮助文件里面有详细介绍

就这样我们打开了golang的本地文档

接着我们去寻找开头的queue包文档

这里我们结合开头代码可以看到没有显示任何文档

下面我们给它添加一下注释

package queue
// An FIFO queue.
type Queue []interface{}
// Pushes the element into the queue.
func (p *Queue) Push(v interface{}){
	*p = append(*p,v.(int))
}
//Pops element from head.
func (p *Queue) Pop() interface{}{
	head := (*p)[0]
	*p = (*p)[1:]
	return head
}
// Returns if the queue is empty or not.
func (p *Queue) IsEmpty() bool{
	return len(*p) == 0
}

添加完后我们先用命令行查看一下

注释出来了接着我们重启一下6060端口刷新网页

文档成功显示

在go语言中文档的书写是很舒服的没有特别的框框架架

go语言在写注释时// .......文字描述之前多加几个空格 go语言的本地文档会给我们自动加框如下图

除此之外 go语言还提供了一种特殊的文档编写方法

我们按照测试方法在同一包内创建queue_test.go文件

是不是发现这明明就是测试文件创建方法

没错 _test.go文件既可以当做测试文件也可以当做文档生成文件做成文档需要输入关键字Exam

下面是文档生成的例子

package queue

import "fmt"

func ExampleQueue_Pop() {
	q := Queue{1}
	q.Push(2)
	q.Push(3)
	fmt.Println(q.Pop())
	fmt.Println(q.Pop())
	fmt.Println(q.IsEmpty())

	fmt.Println(q.Pop())
	fmt.Println(q.IsEmpty())

	//  Output:
	// 这里我们先随便写 执行成功后会打印正确内容
}

执行后结果为注意go语言自动检查执行结果是否正确

package queue

import "fmt"

func ExampleQueue_Pop() {
	q := Queue{1}
	q.Push(2)
	q.Push(3)
	fmt.Println(q.Pop())
	fmt.Println(q.Pop())
	fmt.Println(q.IsEmpty())

	fmt.Println(q.Pop())
	fmt.Println(q.IsEmpty())

	//  Output:
	//	1
	//	2
	//	false
	//	3
	//	true
}

我们重启godoc -http ：6060

go语言的文档生成是不是很简单

总结一下go语言的文档特点

.用注释写文档

.在测试中加入Example

.使用go doc/godoc 来查看/生成文档

最后总结一下go语言整个测试

.表格驱动测试 go语言通过结构体来实现测试的主体这是语法本身支持的

.代码覆盖有覆盖率及覆盖率调试通过ide进行查看明确又清晰

.性能优化工具通过pprof打开图形可视化性能图依块的大小来调节性能

.http测试通过这个简单的例子从头到尾测试一遍包括代码执行结果覆盖率等

.文档及示例代码 go语言的示例代码输出结果也能进行失败

关于golang如何生成文档

猜你喜欢