proposal: x/pkgsite, go/doc: un-name result parameters starting with an underscore in docs

[bradfitz]

Using a defer func to read/modify a function's results is convenient, except that it requires that you name the results, often unnecessarily, violating the style norms as documented at https://go.dev/wiki/CodeReviewComments#named-result-parameters, adding distracting repetition.

I was complaining about this with @ianlancetaylor @griesemer et al, and me saying how I wished there was a way to reference result parameters without naming them.

It was then counter-proposed that instead of changing the language, we could just change the pkgsite/godoc text+HTML-ifier to hide the named results based on a heuristic, such as names starting with an underscore.

Concretely, the proposal is that functions like:

func ExportedFoo(x int) (_node *Node, _err error) { ... }
func ExportedBar() (_err error) { ... }

... be instead rendered in godoc (either plaintext or HTML) as:

func ExportedFoo(x int) (*Node, error) { ... }
func ExportedBar() error { ... }

The alternative is either putting up with ugly docs, or writing this boilerplate:

func ExportedFoo(x int) (*Node, error) {
    return actualFoo(x)
}

func actualFoo(x int) (node *Node, err error) { ... }

[gabyhelp]

Related Issues and Documentation

• Go Wiki: Go Code Review Comments > Named Result Parameters

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[cespare]

This makes the rendered docs look nice, but now your code has an even uglier name in it which violates new style norms.

[bradfitz]

but now your code has an even uglier name in it which violates new style norms

Like all changes, I think it'd look weird at first and then the convention would grow on us.

Today I write the wrapper func, which is arguably even uglier with so much repetition.

And I tend to name the result retErr instead of err to be very explicit to future readers what the intent is. I think _err would look nicer than retErr, personally.

[jimmyfrasche]

If it's just for err, then #69045 is related (though it's likely decline at this point)

[earthboundkid]

What does go doc do with one underscore and one non-underscore return?

[griesemer]

@earthboundkid We could say that all return parameters must start with an _ for this feature to kick in. If some don't start with an _ then go doc shows them all.

As an aside, starting result parameters with _ might be a useful convention in general. Sometimes result parameters conflict with incoming parameters, and this solves this "what should I name this result" problem.

[magical]

What does go doc do with one underscore and one non-underscore return?

We could say that all return parameters must start with an _ for this feature to kick in. If some don't start with an _ then go doc shows them all.

Another option would be to render the underscore-prefixed names as just _. That's syntactically valid and i think preserves the intent better.

[golightlyb]

The alternative is either putting up with ugly docs, or writing this boilerplate:

I sympathise with the reasoning a lot, but at the point where the public and the private API meet, I don't hate the boilerplate, because there's usually some anyway. But that said, I also don't have strong objections.

Can anyone answer, how does backwards compatibility apply to godoc? Obviously if this change was made, existing Go programs would continue to run and give the same result, but valid Go programs today might generate different docs tomorrow...