Godoc - golang 注释与文档工具
Godoc - golang 注释与文档工具
基本规则
The Go project takes documentation seriously! 所以godoc横空出世了
规则很简单，用其中的一句话就可以说明：
to document a type, variable, constant, function, or even a package, write a regular comment directly preceding its declaration, with no intervening blank line.
只要用一个常见的注释，直接加在声明前，并没有插入的空行，这样就可以自动文档化包，类型，接口，变量，常量…
我举两个错误例子说明一下
以下是没有紧跟声明的错误例子
// Add 两数相加
func Add(n1,n2 int)int{
return n1+n2
}以下是将注释切开了的错误例子
// Add
// 两数相加
func Add(n1,n2 int)int{
return n1+n2
}正确的应该是以下：
// Add 两数相加（这一行会被截取为简短介绍）
// 两数相加的注意事项以及原理（这一行作为超级详细的介绍）
func Add(n1,n2 int)int{
return n1+n2
}同时需注意，注释需以 它描述的东西的名字 开发（比如上例中，是描述一个func，就已这个func的name开头 – Add），可以方便godoc在转html或者unix man page的时候，截取它的简短介绍
包
基本可以分为三种：
小型：比如 sort 包，只有两行
中型：比如 gob 包，很多行
重型：比如 strconv 包，使用了doc.go文件来专门保存包注释
不管你写这三种中的哪种，和上面一样，包注释的第一行，出现在godoc的 package list 中
Bug
所有不没有紧临声明的注释都会被godoc省略掉，除了一种情况：
// OldAdd 两数相加
//
// BUG(zhaojun) 明显加错了
func OldAdd(n1,n2 int)(result int){
return n1
}如上，已 BUG(who) 开头的注释，会显示到文档底部Bugs部分，who是可以提供更多信息的人名
不建议
// Deprecated: OldAdd 老旧的方法，不建议使用了
func OldAdd(n1,n2 int)(int){
return n1+n2
}如果一个方法，一个包，一个结构不建议使用了，就可以在前面加上 Deprecated:，表示不建议使用，ide中也会显示不建议使用的提示
段落
还有一些在 godoc 转化注释到html中的注意事项
下一行会在转化时，作为同一个段落，如果要分段落，比如在其中插入空行（如bug实例中）
// 第一段 1. // 还是第一段 1. // // 第二段 2. // 还是第二段 2.会显示为：
第一段 1.还是第一段 1. 第二段 2.还是第二段 2.
代码块
需要预格式化（比如示例代码）的部分，只要使用缩进即可
// You can embed blocks of code in your godoc, such as this:
// fmt.Println("Hello")
// To do that, simply add an extra indent to your comment's text.fmt.Println会以代码块的方式显示
标题
// Sentence 1
//
// Sentence 2会显示为：
Sentence 1
Sentence 2
// Sentence 1.
//
// Sentence 2.会显示为为
Sentence 1.
Sentence 2.
Github
如果你的golang项目上传了github，可以通过特殊的url，看到自己的库的文档，如下:
https://godoc.org/github.com/fluhus/godoc-tricks // 这是生成的文档地址
https://github.com/fluhus/godoc-tricks // 这是对应的github库地址
Example
代码的例子应该写在 _test.go 的文件里，如：
func ExampleAdd() {
fmt.Println(Add(1,2))
// Output: 3
}Local
godoc -http="6060"然后输入url 127.0.0.1:6060/pkg/your.pkg.name，your.pkg.name 替换为你的包的名字
就可以看到你的包的文档了
我的一个简单例子:
// math.go 文件
// smath 提供一些简单的数学函数
package smath
import "errors"
// Math 其实啥都没做
type Math struct{
simplenumber int
}
// Error 没有做啥的error
var (
ErrorSimple = errors.New("simple err")
ErrorNotSimple = errors.New("not simple err")
)
// New 创建一个Math对象
func New()*Math{
return &Math{}
}
// Add 两数相加
//
// result := Add(1,2)
// result = 3
//
// 欢迎使用
func Add(n1,n2 int)(result int){
return n1+n2
}
// BadAdd 两数相加
//
// BUG(zhaojun) 明显加错了
func BadAdd(n1,n2 int)(result int){
return n1
}
// Deprecated: OldAdd 老旧的方法，不建议使用了
func OldAdd(n1,n2 int)(int){
return n1+n2
}
// Add 两数相加
func (m *Math)Add(n1,n2 int)int{
return n1+n2
}
// add 非外部方法
func add(n1,n2 int) int {
return n1+n2
}// math_test.go 测试文件
package smath
import "fmt"
func ExampleAdd() {
fmt.Println(Add(1,2))
// Output: 3
}
参考资料
godoc 官方博文
godoc 技巧