-
Notifications
You must be signed in to change notification settings - Fork 17.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
proposal: x/pkgsite, go/doc: un-name result parameters starting with an underscore in docs #69867
Comments
Related Issues and Documentation (Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.) |
This makes the rendered docs look nice, 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 |
If it's just for err, then #69045 is related (though it's likely decline at this point) |
What does go doc do with one underscore and one non-underscore return? |
@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. |
Another option would be to render the underscore-prefixed names as just |
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... |
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:
... be instead rendered in godoc (either plaintext or HTML) as:
The alternative is either putting up with ugly docs, or writing this boilerplate:
The text was updated successfully, but these errors were encountered: