前言
最开始写 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 方法注意
-
文档注释与对应内容之间不能有空行.
-
godoc只会对公共内容生成文档, 私有内容不会展示.
GO的文档还有更多, 这里只是简单的整理一下, 对于之后写项目基本够用了, 再也不会在写 GO 文档的时候懵逼了. GO 既然已经提供了godoc这么好的工具, 那写文档就更是义不容辞的工作了.
がんばる!!!