约定
最后更新于：2022-04-02 02:50:59
[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 显示语法高亮
';