怎样为Golang模块添加文档示例使用Example测试生成文档片段-Golang-PHP中文网

怎样为Golang模块添加文档示例使用Example测试生成文档片段

P粉602998670

发布： 2025-07-20 09:08:02

原创

930人浏览过

在 golang 模块中推荐使用 example 函数添加文档示例，1. 函数名必须以 example 开头，可对应函数、类型或方法命名；2. 最后一行注释需为 // output: 后跟预期输出，确保测试可验证；3. 示例应简洁完整，包含必要导入和打印语句；4. 将 example 函数放在对应包的 _test.go 文件中，便于组织与测试；5. 可编写多个示例函数展示不同调用场景，提升文档可读性与实用性。

怎样为Golang模块添加文档示例使用Example测试生成文档片段

为 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: 后跟预期输出。否则该示例不会被识别为可执行测试。
尽量保持简洁但完整
示例应该足够简单，让人一眼看懂；但也要包含必要的导入和打印语句，使其能独立运行。

示例：

Calliper 文档对比神器

文档内容对比神器

查看详情

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
}

登录后复制

这样用户可以看到不同输入下的行为差异。

此外，注意：