文档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
等关键字上面并且紧邻关键字的注释才会被展示。
package banana
type, const, func
以名称为注释的开头, package
以Package name
为注释的开头。
package banana
const Xyz = 1
type Abc struct {}
func Bcd() {}
package banana
Package
的注释如果超过3行, 应该放在当前包目录下一个单独的文件中。- 在无效注释中以BUG(who)开头的注释, 将被识别为已知bug, 显示在bugs区域。
package banana
- 如果
bug
注释和关键字注释中间无换行, 那么混合的注释将被显示在bugs
和godoc
列表两个区域内。
package banana
package banana
Example
- 文件必须放在当前包下
- 文件名以
example
开头, _
连接, test
结尾, 如:example_xxx_test.go
- 包名是当前包名
+ _test
, 如: strings_test
- 函数名称的格式
func Example[FuncName][_tag]()
- 函数注释会展示在页面上
- 函数结尾加上
// Output:
注释, 说明函数返回的值
package banana_test
func Example() {
fmt.Println("Hello OverView")
}
func Example_noOutput() {
fmt.Println("Hello OverView")
}
func ExamplePeel() {
fmt.Println("Hello Banana")
}
func ExamplePeel_big() {
fmt.Println("Hello Banana")
}