6.3.3　示例函数

在godoc生成的文档中有一些示例对函数的描述非常形象，这些示例以使用方法以及输出描述为主，比如Copy函数会以如图6-2所示的方式描述。

这是一种交互式的说明文档，其使用更为形象直观。其实这种文档的底层实现就是本节要介绍的示例函数Example。

Example函数也是通过 go test工具来运行的，它的使用一般有三个目的：

▪第一个目的就是文档的作用，相当于在说明函数的时候举了一个形象的例子。与文档不同，Example是需要编译的，所以保证了与代码的同步性和可用性。

▪第二个目的就是在执行go test命令时，进行可运行测试。Example函数中如果有 // output:注释，那么go test执行时就会把输出的结果与注释处的结果进行匹配。

▪第三个目的是交互性测试代码，比如图6-2结合了Go Playground，让用户可在浏览器中编辑和运行示例函数。图6-2中的内容，可以访问以下网址来查看：https://golang.org/pkg/io/#example_Copy。

在使用Example函数时，也要求示例函数写在以_test.go结尾的文件中。Example函数的命名规则要求必须以Example开始，并且函数没有任何参数。

来看一个简单的示例，先写一个求和的函数：

---

book/ch06/6.3/example/testExam.go
1. package exam
2.
3. func Sum(a,b int) int {
4.     return a+b
5. }

---

接下来写一个示例函数：

---

1. package exam
2.
3. import (
4.     "fmt"
5.     _ "testing"
6. )
7.
8. func ExampleSum() {
9.     fmt.Println(Sum(1,2))
10.     // Output:
11.     // 3
12. }

---

可以使用go test命令来检查函数的执行结果是否符合预期：

---

$ go test testExam.go exam_test.go -v
=== RUN   ExampleSum
--- PASS: ExampleSum (0.00s)
PASS
ok      command-line-arguments  0.005s

---

可以看到，结果是PASS。这就是示例函数的写法，此处仅仅是一个简单的例子。在一些大型项目上，往往还需要通过第三方工具来生成方便的API文档，这种情况下Example函数的用法会更多。