-
-
Notifications
You must be signed in to change notification settings - Fork 6.4k
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
[Golang][client] Add option for standard Go generated code comment #555
[Golang][client] Add option for standard Go generated code comment #555
Conversation
will this prevent warning of un-commented Exported symbols? |
Standard Go behavior is that uncommented, exported symbol warnings will be suppressed when the machine-generated code comment is present. The files will be ignored by Perhaps we could add a flag to allow builders to decide whether or not they want |
Added generator flag I left the default with the original comment which will allow Tested with:
|
This is what I meant. It is not always ideal to suppress warnings. |
Agree. It seems like there are lots of opinions on this on both sides given different use cases for machine-generated code. The updated PR supports this feature as a optional flag so people of both persuasions can be supported. I updated the samples so Regarding the current generator errors, it seems like there are at least two
The following type of error looks like simple improvement opportunities for our templates, e.g.
The following is an algorithm update. This will also make the client SDK more consistent because
I've created issue #565 to track resolution of these, in addition to |
@@ -13,5 +13,11 @@ | |||
{{#infoEmail}} | |||
* Contact: {{{infoEmail}}} | |||
{{/infoEmail}} | |||
{{^withGoCodegenComment}} | |||
* Generated by: OpenAPI Generator (https://openapi-generator.tech) |
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.
@grokify thanks for the PR. What about replacing this line directly with the following to avoid adding another option?
// Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.
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.
My original commit f31ecad was a simple replace, however, in discussion with @etherealjoy, I agreed it's not ideal to remove the original behavior and that the original behavior should be the default. This is because this Go behavior change seems more appropriate for machine-generated code that humans aren't meant to use or code where there are no resources for documentation. This trigger's Go's special linter handling for machine generated code and disables golint
and thus gometalinter
. The result is that:
- Warnings for exported symbols without comments will be suppressed meaning lack of comments will not be identified
- Warnings for non-standard MixedCase symbol names will be suppressed
For exported symbol comments, it seems generally better to have comments since generated SDKs are expected to be used by humans. Depending on the specification, this can be the majority of warnings. Comments are important in Go because they are automatically displayed in documentation tools like GoDoc similar to the official Go docs. The cases where people indicated a preference for suppression of these warnings seem to be related to when there are no documentation resources available for a legacy / deprecated API. While it’s nice to support legacy / deprecated API use cases, it doesn’t feel like it should be the default behavior.
MixedCase is a different issue since sometimes I personally feel MixedCase linter is too strict. I like names like userId
and serverUrl
because it makes the symbol name more easily parseable and split into "concepts", but I recognize the standard in the Go community here.
There is a way to separate the comment and case behavior, but that involves having golint
issue the warnings and then using gometalinter
to selectively filter the warnings you are not interested in.
So, the thought is to make the comment a non-default option because it will:
- allow users to see comment errors which should be addressed most of the time
- support more customized behavior using a combination of
golint
andgometalinter
- support different behavior for scenarios like legacy / deprecated API use cases
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.
@grokify thanks for the explanation. My feedback was to avoid adding too many options for a generator. I'm ok with this new option given the reason you provided.
…penAPITools#555) * update go generated code comment * update samples for go petstore * update code generation comment * update samples for go petstore * Trigger CI due to previous Shippable race condition * add -DwithGoCodegenComment=true option * reset samples * add withGoCodegenComment=true to bin/go-petstore-withxml.sh * update samples/.../go-petstore-withXml using -DwithGoCodegenComment=true
PR checklist
./bin/
to update Petstore sample so that CIs can verify the change. (For instance, only need to run./bin/{LANG}-petstore.sh
and./bin/security/{LANG}-petstore.sh
if updating the {LANG} (e.g. php, ruby, python, etc) code generator or {LANG} client's mustache templates). Windows batch files can be found in.\bin\windows\
.master
,3.1.x
,4.0.x
. Default:master
.@antihax
@bvwells
Description of the PR
Update the generated code comment to the following official Go pattern:
^// Code generated .* DO NOT EDIT\.$
This allows the auto-generated code to be differentially processed by Go Lint as discussed here:
This is also used by Go Report Card.