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语言的示例代码输出结果也能进行失败