【Go语言设计与实践】代码即文档

软件工程中有一句话叫做 代码即文档，就是说理想条件下我们通过阅读代码就能够比较好的理解软件的设计思路以及功能。为了更好的维护软件和文档，通常采用的方式是将文档和软件结合在一起，这样文档方便书写，同时也利于维护。

类似于Python中的docstring 和Java里面的Javadoc，Go也提供了文档化工具godoc。

它通过解析源代码，包括注释，可以产生不同格式的文档(HTLM，或者txt文件)。与此同时，如果代码开源在github等开放平台中，还可以通过godoc.org自动生成对应的文档，并且可以仅仅通过点击链接，从一个函数的文档到该函数的源码实现。

约定

注释符//后面要加空格, 例如: // 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区域, 示例
1
2
3
4
// BUG(who): 我是bug说明

// Package banana ...
package banana
如果bug注释和关键字注释中间无换行, 那么混合的注释将被显示在bugs和godoc列表两个区域内
1
2
3
// 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
}