api - 如何在 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.
}

当整个测试文件包含一个示例函数、至少一个其他函数、类型、变量或常量声明，并且没有测试或基准函数时，整个测试文件将作为示例呈现。

有关详细信息，请参阅测试包的文档。