Golang文档函数参数

Question

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

为什么会省略这个？

- Justin Lin

---

类型已经是声明的一部分。含义已经包含在名称中。如果需要其他信息，应该放在文档头中。 - user4466350

Answer 1

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

- Adrian

---

提供的链接并没有展示开发者如何实现这个功能，只是展示了文档处理工具加工后的结果。 - Nathaniel Ford

@NathanielFord 不是这样的；点击任何函数名称，它将带您到源代码，您可以在那里看到产生文档的注释。 - Adrian

如果你知道该怎么做并且足够幸运，那么在四到五次点击后，你就能找到描述有关参数的附加信息的函数。但该页面上的许多链接都不会导向源代码，而这正是原帖和大多数新手开发人员所寻找的东西。 - Nathaniel Ford

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来完成大部分重型工作。

- Nathaniel Ford

---

如果想要重命名s或i，自动重命名文档中的引用并不起作用（例如在IntelliJ中）。 - Ustaman Sangat

有些 IDE 可以做到这一点 - 我使用的是一个内部公司工具，它与 VSCode 相关，因此我认为它至少在某些情况下可以。我同意，为 IDE 编写插件是更困难的事情，但这是 golang 创作者们所做出的决定。因此，当我说 “Golang 更喜欢…” 时，我的意思是 golang 作者将其作为标准。无论它是否合理、正确、好或其他任何东西…那都是观点问题，与此无关。 - Nathaniel Ford

每次我试图提高我的代码质量时，我都会重新阅读文档标准，但它的粗糙程度总是让我感到困惑。是否有一个非官方的文档标准指南，对其他语言的程序员来说更加常规？我明白，如果你是个天才，可能能立刻理解一个函数的50个缩写参数意味着什么，但我认识到我永远不会那么聪明。 - Indrid Cold

@IndridCold 这也是我对Go语言的抱怨，但同时也是一种观点，无关紧要。我认为它坚持了C和C++中流行的某些标准，而在其他地方却被避开，这使得它在这些方面显得特立独行。我特别不喜欢golang代码在垂直和水平方向上都很长，但这显然是作者们想要的。耸肩有时候你必须找到你喜欢的语言特点，并忽略其他一切。 - Nathaniel Ford