Add --omit_package_doc flag (#1702) (#1705)

Makes it possible to omit the package comment from generated code. This is useful if the generated code is added to an existing package that already has package documentation (the generated package comment might be misleading in that case). Co-authored-by: olivierlemasle <[email protected]> Co-authored-by: Rob Percival <[email protected]>
grpc-ecosystem · Sep 28, 2020 · c3ab44e · c3ab44e
1 parent 52bae68
commit c3ab44e
Show file tree

Hide file tree

Showing 4 changed files with 21 additions and 2 deletions.
diff --git a/internal/descriptor/registry.go b/internal/descriptor/registry.go
@@ -109,6 +109,9 @@ type Registry struct {
 	// generateUnboundMethods causes the registry to generate proxy methods even for
 	// RPC methods that have no HttpRule annotation.
 	generateUnboundMethods bool
+
+	// omitPackageDoc, if false, causes a package comment to be included in the generated code.
+	omitPackageDoc bool
 }
 
 type repeatedFieldSeparator struct {
@@ -564,6 +567,16 @@ func (r *Registry) SetGenerateUnboundMethods(generate bool) {
 	r.generateUnboundMethods = generate
 }
 
+// SetOmitPackageDoc controls whether the generated code contains a package comment (if set to false, it will contain one)
+func (r *Registry) SetOmitPackageDoc(omit bool) {
+	r.omitPackageDoc = omit
+}
+
+// GetOmitPackageDoc returns whether a package comment will be omitted from the generated code
+func (r *Registry) GetOmitPackageDoc() bool {
+	return r.omitPackageDoc
+}
+
 // sanitizePackageName replaces unallowed character in package name
 // with allowed character.
 func sanitizePackageName(pkgName string) string {

diff --git a/protoc-gen-grpc-gateway/internal/gengateway/generator.go b/protoc-gen-grpc-gateway/internal/gengateway/generator.go
@@ -183,6 +183,9 @@ func (g *generator) generate(file *descriptor.File) (string, error) {
 		RegisterFuncSuffix: g.registerFuncSuffix,
 		AllowPatchFeature:  g.allowPatchFeature,
 	}
+	if g.reg != nil {
+		params.OmitPackageDoc = g.reg.GetOmitPackageDoc()
+	}
 	return applyTemplate(params, g.reg)
 }
 

diff --git a/protoc-gen-grpc-gateway/internal/gengateway/template.go b/protoc-gen-grpc-gateway/internal/gengateway/template.go
@@ -19,6 +19,7 @@ type param struct {
 	UseRequestContext  bool
 	RegisterFuncSuffix string
 	AllowPatchFeature  bool
+	OmitPackageDoc     bool
 }
 
 type binding struct {
@@ -217,11 +218,11 @@ var (
 // Code generated by protoc-gen-grpc-gateway. DO NOT EDIT.
 // source: {{.GetName}}
 
-/*
+{{if not .OmitPackageDoc}}/*
 Package {{.GoPkg.Name}} is a reverse proxy.
 
 It translates gRPC into RESTful JSON APIs.
-*/
+*/{{end}}
 package {{.GoPkg.Name}}
 import (
 	{{range $i := .Imports}}{{if $i.Standard}}{{$i | printf "%s\n"}}{{end}}{{end}}

diff --git a/protoc-gen-grpc-gateway/main.go b/protoc-gen-grpc-gateway/main.go
@@ -32,6 +32,7 @@ var (
 	allowRepeatedFieldsInBody  = flag.Bool("allow_repeated_fields_in_body", false, "allows to use repeated field in `body` and `response_body` field of `google.api.http` annotation option")
 	repeatedPathParamSeparator = flag.String("repeated_path_param_separator", "csv", "configures how repeated fields should be split. Allowed values are `csv`, `pipes`, `ssv` and `tsv`.")
 	allowPatchFeature          = flag.Bool("allow_patch_feature", true, "determines whether to use PATCH feature involving update masks (using google.protobuf.FieldMask).")
+	omitPackageDoc             = flag.Bool("omit_package_doc", false, "if true, no package comment will be included in the generated code")
 	standalone                 = flag.Bool("standalone", false, "generates a standalone gateway package, which imports the target service package")
 	versionFlag                = flag.Bool("version", false, "print the current version")
 	warnOnUnboundMethods       = flag.Bool("warn_on_unbound_methods", false, "emit a warning message if an RPC method has no HttpRule annotation")
@@ -141,6 +142,7 @@ func applyFlags(reg *descriptor.Registry) error {
 	reg.SetImportPath(*importPath)
 	reg.SetAllowDeleteBody(*allowDeleteBody)
 	reg.SetAllowRepeatedFieldsInBody(*allowRepeatedFieldsInBody)
+	reg.SetOmitPackageDoc(*omitPackageDoc)
 	reg.SetWarnOnUnboundMethods(*warnOnUnboundMethods)
 	reg.SetGenerateUnboundMethods(*generateUnboundMethods)
 	return reg.SetRepeatedPathParamSeparator(*repeatedPathParamSeparator)