-
Notifications
You must be signed in to change notification settings - Fork 1.3k
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
🌱 Refactor godoc for API fields starting with field names #11273
base: main
Are you sure you want to change the base?
Conversation
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
Hi @tsuzu. Thanks for your PR. I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i disagree with
because it disagrees with how Go linters suggest comments for exported objects should be. k8s is quite inconsistent about its Go comments.
Across kube, the godocs that we write on API fields become generated documentation for end users, sometimes in API references, sometimes via If we use the serialised version, then the field description will consistently start with the name of the field as it appears in the yaml, that the user interacts with. If we refer to fields by the Go standard, then the field name will not match what the user interacts with. Most of the time, this is just the case of capitalisation differences, but there are occasions where the serialised and Go field names differ by more than that.
Looking through the core v1 APIs, the majority are actually following the pattern we are suggesting here. There are some exceptions where random fields are with capitals (like Go would expect) and some where they don't even start with the name at all, so fit neither convention. When these APIs were written, the conventions were still being formulated. It's natural that there will be inconsistencies from the early days that haven't been fixed, or the odd occasion where a field was missed during review, but if you were to run an API through a core Kube API review now, all of the current reviewers would enforce this standard. We are writing them with the serialised form to make this easier for the user, as is with most conventions. |
Makes sense to me. For what it's worth over the last few years when reviewing PRs I also tried to enforce that we always refer to fields via the "user-facing" names in error messages and logs. |
The rule that comments should start with field names was enforced by golint, but it's archived. so I think that the rule may not be typical nowadays. |
PR needs rebase. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
What this PR does / why we need it:
Which issue(s) this PR fixes (optional, in
fixes #<issue number>(, fixes #<issue_number>, ...)
format, will close the issue(s) when PR gets merged):This is a part of #11238
/area api