[TOC] ## 約定 1. 在`package, const, type, func`等`關鍵字`上面并且緊鄰關鍵字的注釋才會被展示 ``` // 此行注釋被省略 // 此行注釋被展示 // // 此行注釋被展示2 package banana ``` 3. 推薦 `type, const, func`以名稱為注釋的開頭, `package`以`Package name`為注釋的開頭 ``` // Package banana ... package banana // Xyz ... const Xyz = 1 // Abc ... type Abc struct {} // Bcd ... func Bcd() {} ``` 4. 有效的關鍵字注釋不應該超過`3`行 ``` // Package banana ... // ... // ... // 最好不要超過三行 package banana ``` 5. `Package`的注釋如果超過`3`行, 應該放在當前包目錄下一個單獨的文件中, 如:[doc.go](https://link.jianshu.com?t=https://golang.org/pkg/encoding/gob/) 6. 如果當前包目錄下包含多個`Package`注釋的go文件(包括`doc.go`), 那么按照**文件名的字母數序**優先顯示 ``` //----- doc.go ----- // Package banana ...第一個顯示 package banana //----- e.go ----- // Package banana ...第二個顯示 package banana //----- f.go ----- // Package banana ...第三個顯示 package banana ``` 7. `Package`下的同名`Package.go`的注釋會出現在godoc的 8. 在無效注釋中以`BUG(who)`開頭的注釋, 將被識別為已知bug, 顯示在`bugs`區域, [示例](http://golang.org/pkg/bytes/#bugs) ``` // BUG(who): 我是bug說明 // Package banana ... package banana ``` 12. URL將被轉化為HTML鏈接 13. table 顯示語法高亮