Question

阅读godoc doc。它没有说明如何记录函数参数。

省略这个的原因是什么？

Answer 1

godoc中没有明确的函数参数文档。超出参数名称的任何必要细节都应该进入函数的doc注释。有关示例，请参阅every function in the standard library。

Answer 2

Golang 更喜欢一种风格，其中函数签名是“自我记录”，因为参数/参数名称及其类型的组合应该在很大程度上具有解释性。附加信息应以自然语言样式在文档标题中提供。来自 golang example.go

// splitExampleName attempts to split example name s at index i,
// and reports if that produces a valid split. The suffix may be
// absent. Otherwise, it must start with a lower-case letter and
// be preceded by '_'.
//
// One of i == len(s) or s[i] == '_' must be true.
func splitExampleName(s string, i int) (prefix, suffix string, ok bool) {
    if i == len(s) {
        return s, "", true
    }
    if i == len(s)-1 {
        return "", "", false
    }
    prefix, suffix = s[:i], s[i+1:]
    return prefix, suffix, isExampleSuffix(suffix)
}

在这里，我们看到有关 s 和 i 的详细信息包含在函数前面的摘要说明中。同样，关于返回值的注释也包含在该段落中。这与 Java 或 Python 或其他语言不同，后者为这些细节中的每一个都提出了更正式的结构。这样做的原因是 Golang 风格通常针对简洁性和灵活性进行了优化，避开了其他语言的规范性风格指南方法，并依靠 gofmt 来完成大部分繁重工作。

Golang doc func参数

2 个答案: