GoDoc的使用
摘要：
一. 約定
註釋符//
後面要加空格, 例如:// xxx
在package, const, type, func
等關鍵字
上面並且緊鄰關鍵字的註釋才...
一. 約定
-
註釋符
//後面要加空格, 例如:// 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行, 應該放在當前包目錄下一個單獨的檔案中, 如:ofollow,noindex">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 */
二. 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