Godoc中的Example编写

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

转载于:https://my.oschina.net/aiilive/blog/512866