[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 显示语法高亮