在 golang 模块中推荐使用 example 函数添加文档示例，1. 函数名必须以 example 开头，可对应函数、类型或方法命名；2. 最后一行注释需为 // output: 后跟预期输出，确保测试可验证；3. 示例应简洁完整，包含必要导入和打印语句；4. 将 example 函数放在对应包的 _test.go 文件中，便于组织与测试；5. 可编写多个示例函数展示不同调用场景，提升文档可读性与实用性。
为 Golang 模块添加文档示例，最推荐的方式是使用 Example 函数来生成文档片段。这种方式不仅能让代码的使用者更直观地了解函数或类型的用法，还能在运行测试时自动执行这些示例，确保它们不会过期。
什么是 Example 测试？
Go 的文档系统 godoc 支持从 _test.go 文件中提取以 Example 开头的函数，并将其作为文档的一部分展示出来。这些函数不仅可以作为示例说明用途，还会在 go test 中被执行，起到验证作用。
例如，你写了一个字符串拼接函数：
立即学习“go语言免费学习笔记（深入）”；
func JoinStrings(a, b string) string {
return a + b
}你可以添加一个对应的 Example 函数：
func ExampleJoinStrings() {
fmt.Println(JoinStrings("hello", "world"))
// Output: helloworld
}这个示例会在 godoc 页面上显示，并且在测试中会被执行，确保输出与注释一致。
如何编写有效的 Example 示例？
-
命名规范
- 函数名必须以
Example开头。 - 如果是某个函数的示例，可以命名为
ExampleFuncName。 - 如果是某个类型的方法，可以用
ExampleTypeName_MethodName。 - 也可以单独为类型写示例：
ExampleTypeName。
- 函数名必须以
输出注释必须准确
示例函数中的最后一行注释必须是// Output:后跟预期输出。否则该示例不会被识别为可执行测试。尽量保持简洁但完整
示例应该足够简单，让人一眼看懂；但也要包含必要的导入和打印语句，使其能独立运行。
示例：
func ExampleJoinStrings() {
result := JoinStrings("go", "lang")
fmt.Println(result)
// Output: goland
}在模块中组织 Example 测试
- 把
Example函数放在对应的_test.go文件中。 - 如果模块结构较复杂，建议每个包都有自己的
_test.go文件。 - 使用
go doc或godoc命令查看生成的文档效果。 - 推荐结合
go test来验证示例是否通过。
例如，在项目结构中：
my-module/ ├── stringutil/ │ ├── join.go │ └── join_test.go
在 join_test.go 中编写示例函数即可。
小技巧：多情况展示和注释格式
如果你希望展示多个调用场景，可以在同一个 Example 函数里写多个调用，或者拆分成多个 ExampleXXX 函数。
比如：
func ExampleJoinStrings_emptyInput() {
fmt.Println(JoinStrings("", "world"))
// Output: world
}
func ExampleJoinStrings_withSpace() {
fmt.Println(JoinStrings("hello ", "world"))
// Output: hello world
}这样用户可以看到不同输入下的行为差异。
此外，注意：
- 不要省略
fmt.Println，否则无法捕获输出。 - 输出内容要完全匹配，包括空格和换行。
基本上就这些。写好 Example 文档不仅能提升模块的可读性，也能提高代码的可靠性。不复杂但容易忽略的是保持示例与实现同步更新，建议每次修改接口时都检查一遍对应的示例是否还有效。
