关于golang如何生成文档

转：https://blog.csdn.net/weixin_42654444/article/details/82221983

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