如何在Go中向API文档添加示例？

Question

Go标准库中有一些不错的可执行示例。如何将这样的示例添加到我自己的API文档中？

Answer 1

输出$ go help testfunc：

“ go test”命令希望在与被测试软件包相对应的“ * _test.go”文件中找到测试，基准测试和示例功能。

测试函数是一个名为TestXXX（其中XXX是任何不以小写字母开头的字母数字字符串）的函数，并且应具有签名，

 func TestXXX(t *testing.T) { ... }

基准函数是一个名为BenchmarkXXX的函数，应具有签名，

 func BenchmarkXXX(b *testing.B) { ... }

示例函数与测试函数相似，但是不使用* testing.T报告成功或失败，而是将输出打印到os.Stdout和os.Stderr。将该输出与函数的“ Output：”注释进行比较，该注释必须是函数主体中的最后一个注释（请参见下面的示例）。没有这样的注释，或在“ Output：”之后没有文本的示例已编译但未执行。

Godoc显示ExampleXXX的主体，以演示函数XXX，常数或变量的用法。接收器类型为T或* T的方法M的示例名为ExampleT_M。对于给定的函数，常量或变量，可能有多个示例，以尾随_xxx加以区分，其中xxx是不以大写字母开头的后缀。

这是一个示例示例：

func ExamplePrintln() {
        Println("The output of\nthis example.")        
        // Output: The output of
        // this example.}

当整个测试文件包含单个示例函数，至少一个其他函数，类型，变量或常量声明，并且不包含测试或基准测试函数时，将以示例形式显示。

有关更多信息，请参见测试包的文档。