Question

文档过程的一部分是生成示例代码来展示包的某些或所有函数和类型的使用。

示例函数有很多好处，包括它们是由 go test 执行的可执行测试！因此，如果一个示例函数有一个 // Output: 行，go test 工具将检查经过计算的输出是否和 // Output: 行后的值相匹配。

另外，当在包里看到示例时是非常有用的，这是下节的主题。最后，Go 文档服务器（https://golang.org/pkg/io/）上显示的示例函数允许读者使用示例代码进行实验。Go 训练场https://play.golang.org/也支持这个功能。

由于 go test 子命令负责程序的示例，您需要引入 testing 标准包，并包含示例函数在以 _test.go 结尾的 Go 文件中。而且，每个示例函数的名称必须以 Example开头。最后，示例函数 不接收参数并没有返回结果！

现在，让我们来给如下存在 ex.go 中的包创建一些示例函数：

package ex
func F1(n int) int {
    if n == 0 {
        return 0
    }
    if n == 1 || n == 2{
        return 1
    }
    return F1(n-1) + F1(n-2)
}

func S1(s string) int {
    return len(s)
}

ex.go 源文件包含名为 F1() 和 S1() 两个函数的实现。注意，ex.go 不需要引入 fmt 包。

如您所知，示例函数将存在 ex_test.go 文件中，分三部分来介绍。

ex_test.go 的第一部分如下：

package ex
import (
    "fmt"
)

ex_test.go 的第二段代码如下：

func ExampleF1() {
    fmt.Println(F1(10))
    fmt.Println(F1(2))
    // Output:
    // 55
    // 1
}

ex_test.go 剩下的代码如下：

func ExampleS1() {
    fmt.Println(S1("123456789"))
    fmt.Println(S1(""))
    // Output:
    // 8
    // 0
}

对 ex.go 包执行 go test 命令会产生如下输出：

$ go test ex.go ex_test.go -v
=== RUN ExampleF1
--- PASS: ExampleF1 (0.00s)
=== RUN ExampleS1
--- FAIL: ExampleS1 (0.00s)
got:
9
0
want:
8
0
FAIL
FAIL command-line-arguments 0.006s

您将注意到上面的输出告诉我们，基于 // Output: 注释后面的数据，S1() 函数有错误。