英文:
How to add examples to API documentation in Go?
问题
在Go标准库中有一些很好的可执行示例。我如何将这样的示例添加到我的API文档中？
英文:
There are some nice executable examples in the Go standard library. How can I add such an example to my own API documentation?
答案1
得分: 11
$ 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.
}
> 当测试文件包含单个示例函数、至少一个其他函数、类型、变量或常量声明，并且没有测试或基准测试函数时，整个测试文件将作为示例呈现。
>
> 有关更多信息，请参阅testing包的文档。
英文:
Output of $ go help testfunc:
> The 'go test' command expects to find test, benchmark, and example functions
> in the "*_test.go" files corresponding to the package under test.
>
> A test function is one named TestXXX (where XXX is any alphanumeric string
> not starting with a lower case letter) and should have the signature,
func TestXXX(t *testing.T) { ... }
> A benchmark function is one named BenchmarkXXX and should have the signature,
func BenchmarkXXX(b *testing.B) { ... }
> An example function is similar to a test function but, instead of using *testing.T
> to report success or failure, prints output to os.Stdout and os.Stderr.
> That output is compared against the function's "Output:" comment, which
> must be the last comment in the function body (see example below). An
> example with no such comment, or with no text after "Output:" is compiled
> but not executed.
>
> Godoc displays the body of ExampleXXX to demonstrate the use
> of the function, constant, or variable XXX. An example of a method M with
> receiver type T or *T is named ExampleT_M. There may be multiple examples
> for a given function, constant, or variable, distinguished by a trailing _xxx,
> where xxx is a suffix not beginning with an upper case letter.
>
> Here is an example of an example:
func ExamplePrintln() {
Println("The output of\nthis example.")
// Output: The output of
// this example.
}
> The entire test file is presented as the example when it contains a single
> example function, at least one other function, type, variable, or constant
> declaration, and no test or benchmark functions.
>
> See the documentation of the testing package for more information.
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库，让每个人都能够通过互相帮助和分享经验来进步。
评论