编写 go 函数文档测试的语法：测试名称包含 example 前缀。测试代码说明函数预期行为。断言验证函数返回值与预期相同。测试覆盖函数的不同使用情况。编写测试有助于改进函数文档，通过示例展示函数使用方式。

如何为 Golang 函数文档编写测试？

在 Go 中，提供一个明确且可读的 API 文档至关重要。函数文档是 API 文档的重要组成部分，因为它提供有关函数用途、参数和返回值的信息。通过编写测试，您可以确保函数文档准确无误并与函数的实际行为相匹配。

语法

以下是编写函数文档测试的语法：

func Example<FunctionName>() {
    // 测试设置
    // 调用函数
    // 断言结果
}

示例

考虑以下函数：

// Add 两数之和
func Add(a, b int) int {
    return a + b
}

以下是如何编写该函数的文档测试：

func ExampleAdd() {
    result := Add(1, 2)
    fmt.Println(result) // 输出: 3
}

注意事项

• 测试名称应包含 Example 前缀。
• 测试代码应清楚地说明函数的预期行为。
• 断言应验证函数的返回值是否与预期相同。
• 测试应覆盖函数的不同使用情况。

实战案例

以下是通过编写测试改进函数文档的实际案例：

原函数文档：

// Distance 计算两点之间的距离
func Distance(x1, y1, x2, y2 float64) float64 {
    // 未提供函数文档
}

添加测试后的函数文档：

// Distance 计算两点之间的距离
//
// 示例：
//
//   Distance(1, 2, 4, 6) == 5
func Distance(x1, y1, x2, y2 float64) float64 {
    // ... 函数实现
}

func ExampleDistance() {
    result := Distance(1, 2, 4, 6)
    fmt.Println(result) // 输出: 5
}

通过编写测试，我们改进了函数文档，并通过明确的示例展示了函数的使用方式。