Golang文档功能参数

Question

阅读godoc doc。它没有指定如何记录功能参数。

省略它的原因是什么？

Answer 1

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大部分繁重的工作。

Answer 2

godoc 中没有明确的函数参数文档。参数名称和类型未涵盖的任何必要细节都应包含在函数的文档注释中。例如，请参阅标准库中的每个函数。