Golang 文档函数参数答案

【问题标题】：Golang doc func parametersGolang 文档函数参数
【发布时间】：2021-06-08 05:20:15
【问题描述】：

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

省略这个的原因是什么？

【问题讨论】：

类型已经是声明的一部分。含义已经是名称的一部分。如果需要其他任何内容，则应进入该文档标题。

标签： go

【解决方案1】：

godoc 中没有明确的函数参数文档。参数名称和类型未涵盖的任何必要细节都应放入函数的文档注释中。例如，请参阅every function in the standard library。

【讨论】：

FWIW，提供的链接没有显示开发人员如何执行此操作的示例 - 仅显示 doctool-masticated 结果是什么。
@NathanielFord 不正确；单击任何函数名称，它将带您进入源代码，您可以在其中看到生成文档的注释。
四五次点击，当然，如果你知道你在做什么，并且幸运地登陆了一个描述有关其参数的附加信息的函数。该页面上的许多链接不会指向源代码，这是 OP 和大多数新手开发人员正在寻找的东西。

【解决方案2】：

Golang 更喜欢函数签名是“自我记录”的风格，因为参数/参数名称及其类型的组合应该在很大程度上是解释性的。应在文档标题中以自然语言样式提供附加信息。来自golangexample.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。

【讨论】：