本文档介绍了如何在 Go 语言中为自定义 API 文档添加可执行示例，类似于 Go 标准库中的示例。通过使用 go test 命令和特定的示例函数格式，可以轻松地在文档中展示代码用法，并确保示例的正确性。本文将详细讲解示例函数的命名规则、格式要求以及注意事项，帮助开发者编写清晰、有效的 API 文档。
示例函数：清晰展示 API 用法的利器
Go 语言提供了一种便捷的方式来为 API 文档添加可执行示例，这些示例可以帮助用户更好地理解和使用你的代码。 这些示例函数与测试函数和基准测试函数类似，都位于 *_test.go 文件中。
示例函数的格式
示例函数的格式有其特定的要求，遵循这些规则才能让 go test 命令正确识别并执行你的示例。
- 命名规则： 示例函数以 Example 开头，后面可以跟上要展示的函数、常量或变量的名称。 如果要为类型 T 或 *T 的方法 M 创建示例，则命名为 ExampleT_M。 为了区分同一个函数、常量或变量的多个示例，可以在名称后添加 _xxx 后缀，其中 xxx 是一个非大写字母开头的后缀。
- 函数签名： 示例函数没有参数和返回值。
- 输出验证： 示例函数的输出会与函数体中最后一个注释 // Output: 后面的内容进行比较。 如果示例函数没有 // Output: 注释，或者注释后没有任何文本，则该示例会被编译但不会被执行。
下面是一个 Println 函数的示例：
func ExamplePrintln() {
Println("The output of\nthis example.")
// Output: The output of
// this example.
}示例函数的执行与展示
go test 命令会执行示例函数，并将输出与 // Output: 注释中的内容进行比较。 如果两者一致，则测试通过，否则测试失败。
godoc 工具会将 ExampleXXX 函数的主体部分展示出来，用于演示 XXX 函数、常量或变量的使用方法。
完整示例文件的特殊情况
如果整个测试文件只包含一个示例函数，且至少包含一个其他函数、类型、变量或常量的声明，并且没有测试或基准测试函数，那么整个测试文件都会被作为示例展示。
注意事项
- 确保 // Output: 注释中的内容与示例函数的实际输出完全一致，包括空格和换行符。
- 可以使用多个示例函数来展示 API 的不同用法。
- 示例函数应该简洁明了，易于理解。
- 利用示例函数可以有效地提升 API 文档的质量，帮助用户快速上手。
总结
通过本文，你学习了如何在 Go 语言中为 API 文档添加可执行示例。 掌握示例函数的命名规则、格式要求以及注意事项，可以帮助你编写清晰、有效的 API 文档，提升代码的可读性和易用性。 善用示例函数，可以极大地改善用户体验，让你的 API 更受欢迎。
