17. Go-文档doc

文档doc

• 每一个 package 都应该有相关注释，在 package 语句之前的注释内容将被默认认为是这个包的文档， package 的注释应该提供一些相关信息并对整体功能做简要的介绍。
• 在日常开发过程中，可以使用go doc和godoc命令生成代码的文档。

go doc 用法

• go doc 命令打印Go语言程序实体上的文档。可以使用参数来指定程序实体的标识符。
• go doc 用法 go doc [-u] [-c] [package|[package.]symbol[.methodOrField]]
  • -all 显示所有文档
  • -c 匹配程序实体时，大小写敏感
  • -cmd将命令（main包）视为常规程序包，如果要显示main包的doc，请指定这个标识
  • -src显示完整源代码
  • -u显示未导出的程序实体

使用示例

• 输出指定 package ，指定类型，指定方法的注释

go doc sync.WaitGroup.Add

• 输出指定 package ，指定类型的所有程序实体，包括未导出的

 go doc -u -all sync.WaitGroup

• 输出指定 package 的所有程序实体（非所有详细注释）

 go doc -u sync

通过网页查看文档

• 命令 godoc -http=:6060。
• godoc会监听6060端口，通过网页访问 http://127.0.0.1:6060。

编写自己的文档

文档编写的约定

• 注释符//后面要加空格, 例如: // xxx
• 在package, const, type, func等关键字上面并且紧邻关键字的注释才会被展示。

// 此行注释被省略

// 此行注释被展示 
// 
// 此行注释被展示xxxxxxx
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行, 应该放在当前包目录下一个单独的文件中。
• 在无效注释中以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
*/

• 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
}