Godoc
godoc
工具可以从go
程序中抽取出并生成文档,抽取的内容来自go
代码中的注释,以及本文中将要讲到的源代码包下的example_test.go
文件。
起因
Go语言还算是比较新的东西,学习资料并不是太多。在查看go的document的时候,看到Example
的时候有些纳闷,代码文档注释中并没有标识那些东西作为Example
,于是查看了源代码包,发现了example_test.go
这个文件,原来猫腻在这里,通常在一个包下添加该文件后,就可以在里面添加Example
。
经过
查看example_test.go
的文件内容之后得出了以下结论:
- 如果为函数添加
Example
, 直接在example_test.go
文件中添加函数func Example{要提供示例的函数名}
func ExampleDesEncrypt() {
var data = "Hello World !"
var goodkey = "abcd1234"
security, err := DesEncrypt([]byte(data), []byte(goodkey))
if err != nil {
t.Error(err)
}
d, err := DesDecrypt(security, []byte(goodkey))
if err != nil {
log.Fatal(err)
}
if string(d) != data {
log.Fatal(data, goodkey, string(security), string(d))
} else {
log.Println("Ok")
}
}
- 如果为方法添加
Example
, 直接在example_test.go
文件中添加函数func Example{方法接受者结构体类型名}_{要提供示例的方法名}
func ExampleCutImage_CutSrcImage() {
var src = "src.png"
var w, h = 100, 100
for i := 20; i < 800; i += 100 {
var cutIamge = CutImage{
SrcImageFileName: src,
DestImageFileName: "dest" + strconv.Itoa(i) + ".png",
DestImageWidth: w,
DestImageHeight: h,
SrcImageStartPoint: image.Point{X: i, Y: i},
}
//裁剪图片
err := cutIamge.CutSrcImage()
if err != nil {
log.Fatal(err)
}
}
}
- 如果为类型添加
Example
,直接在example_test.go
文件中添加函数fun Example{类型名}
func ExampleCutImage() {
var cutIamge = CutImage{
SrcImageFileName: "src.png",
DestImageFileName: "dest.png",
DestImageWidth: 100,
DestImageHeight: 100,
SrcImageStartPoint: image.Point{X: 0, Y: 0},
}
_ := cutIamge.CutSrcImage()
}
- 如果添加Example的函数名,类型名,方法名不存在,将会在godoc抽取生成文档是忽略,如下:
2015/09/30 14:45:28 skipping example 'ExampleCutSrcImage' because 'CutSrcImage' is not a known function or type
2015/09/30 14:52:53 skipping example 'ExampleCutImage_CutSrcImage2' because 'CutImage_CutSrcImage2' is not a known function or type
结果
通过为ximage
包,xdes
包中的函数添加Example
可以使得初次使用的时候更容易获得正确的使用方法。
下面秀出在go document
中Example的具体效果:
图a: Go Document中的Example展示部分
图b: ximage包中的类型方法Example
图c: xdes包中的函数Example