一. 約定
注釋符
//后面要加空格, 例如:// 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
