软件工程中有一句话叫做 代码即文档,就是说理想条件下我们通过阅读代码就能够比较好的理解软件的设计思路以及功能。为了更好的维护软件和文档,通常采用的方式是将文档和软件结合在一起,这样文档方便书写,同时也利于维护。
类似于Python中的docstring
和Java里面的Javadoc
,Go也提供了文档化工具godoc
。
它通过解析源代码,包括注释,可以产生不同格式的文档(HTLM,或者txt文件)。与此同时,如果代码开源在github等开放平台中,还可以通过godoc.org
自动生成对应的文档,并且可以仅仅通过点击链接,从一个函数的文档到该函数的源码实现。
约定
注释符
//
后面要加空格, 例如:// xxx
在
package, const, type, func
等关键字
上面并且紧邻关键字的注释才会被展示1
2
3
4
5
6// 此行注释被省略
// 此行注释被展示
//
// 此行注释被展示2
package bananatype, const, func
以名称为注释的开头,package
以Package name
为注释的开头1
2
3
4
5
6
7
8
9
10
11// Package banana ...
package banana
// Xyz ...
const Xyz = 1
// Abc ...
type Abc struct {}
// Bcd ...
func Bcd() {}有效的关键字注释不应该超过
3
行1
2
3
4
5// Package banana ...
// ...
// ...
// 最好不要超过三行
package bananaPackage
的注释如果超过3
行, 应该放在当前包目录下一个单独的文件中, 如:doc.go如果当前包目录下包含多个Package注释的go文件(包括doc.go), 那么按照文件名的字母数序优先显示
1
2
3
4
5
6//----- doc.go -----
/*
...第一个显示
*/
package banana1
2
3
4//----- e.go -----
// Package banana ...第二个显示
package banana1
2
3
4//----- f.go -----
// Package banana ...第三个显示
package bananaPackage
的注释会出现在godoc的包列表中, 但只能展示大约523字节的长度在无效注释中以
BUG(who)
开头的注释, 将被识别为已知bug, 显示在bugs
区域, 示例1
2
3
4// BUG(who): 我是bug说明
// Package banana ...
package banana如果
bug注释
和关键字注释
中间无换行, 那么混合的注释
将被显示在bugs
和godoc列表
两个区域内1
2
3// BUG(who): 我是bug注释
// Package banana ...也是pkg注释
package banana段落:
1
2
3
4
5
6
7
8
9
10
11
12/*
abc ... bcd
Basic(字体加粗变蓝需首字母大写, 中文加粗变蓝需要加上一个大写字母)
abc
...
... 属于Basic的段落
...
bcd
*/
package banana预格式化:
1
2
3
4
5
6
7/*
abc ... bcd
Abc(不会加粗变蓝, 预格式化和段落不能同时存在)
abc ... 预格式化需要缩进 ... bcd
*/URL将被转化为HTML链接
Example
- 文件必须放在当前包下
- 文件名以
example
开头,_
连接,test
结尾, 如:example_xxx_test.go
- 包名是
当前包名
+_test
, 如:strings_test
- 函数名称的格式
func Example[FuncName][_tag]()
- 函数注释会展示在页面上
- 函数结尾加上
// Output:
注释, 说明函数返回的值
1 | // 文件必须放在 banana包目录下, 名字必须为example_xxx_test.go |
Github
如果你的golang项目上传了github,可以通过特殊的url,看到自己的库的文档,如下:
https://godoc.org/github.com/SimpCosm/algorithms/strings/kmp // 这是生成的文档地址
https://github.com/SimpCosm/algorithms/strings/kmp // 这是对应的github库地址
本地调试
1 | godoc -http=":6060" |
Todo
- 如何现实成main函数的,并且能够跑Goplayground