前言

最开始写 GO 的时候, 发现方法的注释并不支持@param, @return等参数, 搞得我都不知道该如何给自己的方法写文档说明了. 而且网上搜了搜也没有搜到教程, 甚是郁闷.

今天找到了GO内置的文档工具: godoc. (我用的1.14.3版本貌似不是自带工具了, 需要安装(配置代理): go get golang.org/x/tools/cmd/godoc)

运行命令: godoc -http=:8888. 可以直接在本地浏览器访问8888端口, 查看这个运行在本地的文档服务: localhost:8888. 能够看到所有官方包的文档. 而这些文档内容都是从官方代码包中读取的.

这个文档工具不光能够检测官方文档, 还能够检测自己的项目, 只要将项目配置到GOPATH下即可.

既然人家官方代码能生成文档, 那就说明是有文档生成格式的呀. 既然我不知道如何写文档, 抄官方的样式不就行了么? nice. 以下是我多处借鉴后, 总结的 GO 文档书写规则.

文档

经过测试, GO 的文档格式, 全局变量/常量/函数/结构体/接口/包等等, 声明格式都一样, 会读取对应内容上方紧跟着的注释内容. 所以就对文档格式统一介绍即可.

文档格式

书写格式

文档的书写影响其展示形式, 如下所示:

/*
这是一个展示文档作用的包.

A 标题

这里的标题为首字母大写, 且后面没有标点.
如果没有空行, 则文档不会换行.

B标题二

GO 的文档工具只识别首字母大写, 不识别中文, 有点难受.
 开头空格标识缩进
 */
// 同时, 也可以写成多个单行注释的形式
package doc

展示形式:

对于包的说明文档, 因为包下每个文件都有package doc 这段代码, 如果包下有多个文件都对此包进行了说明, 文档会将所有说明拼接到一起. 可以单独建一个doc.go的空文件, 专门用来写包文档. (fmt 包就是这么搞的)

全局变量/常量/方法/结构体

全局变量/常量/方法/结构体等内容, 文档会对其进行归类, 只要将说明加到其上方即可. 简单写个常量看看, 其他同理:

// test const
const TestConst = "const"

示例代码

与写单元测试类似, 新建一个example_test.go文件. 在其中写 demo 函数, 会检测同名以Example开头的函数:

package doc

import (
   "fmt"
)

func ExampleDemoTest() {
   DemoTest()

   // OutPut:
   // 没有返回值
}

// 多个 demo, 下划线后拼单词或数字
func ExampleDemoTest_2() {
   DemoTest()
}

// 包 demo, 对于没有指定方法的, 会识别为这个包的例子
func Example() {
   fmt.Println("aaaa")

   // OutPut:
   // none
}

// 包 demo2
func Example_2() {
   fmt.Println("bbb")
}

godoc检测示例代码:

文档关键字

那 GO 的注释中有没有文档用到的关键字呢? 有, 简单写几个.

BUG

可以对 bug 进行描述, godoc会自动识别并标识出来:

// BUG(hujing): 对 bug 的描述信息

Deprecated

已弃用的标识, 这个关键字看的太多了, 不过godoc并不会识别这个关键字, 主要是编译器识别.

// Deprecated: 请使用 DocDemoNew 方法

注意

1. 文档注释与对应内容之间不能有空行.

2. godoc只会对公共内容生成文档, 私有内容不会展示.

GO的文档还有更多, 这里只是简单的整理一下, 对于之后写项目基本够用了, 再也不会在写 GO 文档的时候懵逼了. GO 既然已经提供了godoc这么好的工具, 那写文档就更是义不容辞的工作了.

がんばる!!!