CODEWITHSUNDEEP
go
Justin Lin
Justin Lin

Reputation: 761

Golang doc func parameters

Reading the godoc doc. It does not specify how function parameters are documented.

What is the reason for omitting this?

Upvotes: 35

Views: 27040

Answers (2)

Nathaniel Ford
Nathaniel Ford

Reputation: 21220

Golang prefers a style wherein the function signature is 'self documenting', in that the combination of a parameter/argument name and it's type should be be largely explanatory. Additional information should be provided in the doc header in a natural language style. From the 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)
}

Here we see that details about s and i are included in the summary description ahead of the function. Similarly, notes about the return values are included in that paragraph. This differs from Java or Python or other languages, which propose a more formal structure for each of these details. The reason for this is that Golang style is typically optimized for concision and flexibility, eschewing the prescriptive style-guide approach of other languages and relying on gofmt for the majority of the heavy lifting.

Upvotes: 15

Adrian
Adrian

Reputation: 46413

There is no explicit documentation of function parameters in godoc. Any necessary details not covered by the name and type of the parameter should go into the doc comment for the function. For examples, see every function in the standard library.

Upvotes: 14

Related Questions