如何在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.该输出与函数的"输出:"注释进行比较,该注释必须是函数体中的最后一条注释(参见下面的示例).在"输出:"之后没有这样的注释或没有文本的示例被编译但未执行.

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

以下是一个示例示例:

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

当整个测试文件包含单个示例函数,至少一个其他函数,类型,变量或常量声明,以及没有测试或基准函数时,它们将作为示例显示.

有关更多信息,请参阅测试包的文档.