一. 约定
注释符
//后面要加空格, 例如:// xxx-
在
package, const, type, func等关键字上面并且紧邻关键字的注释才会被展示// 此行注释被省略 // 此行注释被展示 // // 此行注释被展示2 package banana -
type, const, func以名称为注释的开头,package以Package name为注释的开头// Package banana ... package banana // Xyz ... const Xyz = 1 // Abc ... type Abc struct {} // Bcd ... func Bcd() {} -
有效的关键字注释不应该超过
3行// Package banana ... // ... // ... // 最好不要超过三行 package banana Package的注释如果超过3行, 应该放在当前包目录下一个单独的文件中, 如:doc.go-
如果当前包目录下包含多个
Package注释的go文件(包括doc.go), 那么按照文件名的字母数序优先显示//----- doc.go ----- /* ...第一个显示 */ package banana//----- e.go ----- // Package banana ...第二个显示 package banana//----- f.go ----- // Package banana ...第三个显示 package banana Package的注释会出现在godoc的包列表中, 但只能展示大约523字节的长度-
在无效注释中以
BUG(who)开头的注释, 将被识别为已知bug, 显示在bugs区域, 示例// BUG(who): 我是bug说明 // Package banana ... package banana -
如果
bug注释和关键字注释中间无换行, 那么混合的注释将被显示在bugs和godoc列表两个区域内// BUG(who): 我是bug注释 // Package banana ...也是pkg注释 package banana -
段落:
/* abc ... bcd Basic(字体加粗变蓝需首字母大写, 中文加粗变蓝需要加上一个大写字母) abc ... ... 属于Basic的段落 ... bcd */ package banana -
预格式化:
/* abc ... bcd Abc(不会加粗变蓝, 预格式化和段落不能同时存在) abc ... 预格式化需要缩进 ... bcd */ URL将被转化为HTML链接
二. Example
- 文件必须放在当前包下
- 文件名以
example开头,_连接,test结尾, 如:example_xxx_test.go - 包名是
当前包名+_test, 如:strings_test - 函数名称的格式
func Example[FuncName][_tag]() - 函数注释会展示在页面上
- 函数结尾加上
// Output:注释, 说明函数返回的值
// 文件必须放在 banana包目录下, 名字必须为example_xxx_test.go
// Package banana_test 为banana包的示例
package banana_test
// 此注释将会被展示在页面上
// 此函数将被展示在OverView区域
func Example() {
fmt.Println("Hello OverView")
// Output:
// Hello OverView
}
// 此函数将被展示在OverView区域, 并展示noOutput标签
func Example_noOutput() {
fmt.Println("Hello OverView")
// (Output: )非必须, 存在时将会展示输出结果
}
// 此函数将被展示在Function区域
// Peel必须是banana包实现的方法
func ExamplePeel() {
fmt.Println("Hello Banana")
// Output:
// Hello Banana
}
// 此函数将被展示在Function区域
// Peel必须是banana包实现的方法, 并展示big标签
func ExamplePeel_big() {
fmt.Println("Hello Banana")
// Output:
// Hello Banana
}
三. Command line
开启一个godoc小型server, -play可以使用playground运行Example代码
godoc -http=:6060 -play
