Add --omit_package_doc flag (#1702)

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 <o.lemasle@gmail.com>

Co-authored-by: Rob Percival <robpercival@google.com>

protoc-gen-grpc-gateway/descriptor/registry.go

@@ -94,6 +94,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 {
@@ -542,6 +545,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 {

protoc-gen-grpc-gateway/internal/gengateway/generator.go

@@ -172,6 +172,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)
 }
 

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 {
@@ -221,11 +222,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}}

protoc-gen-grpc-gateway/main.go

@@ -35,6 +35,7 @@ var (
 	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).")
 	allowColonFinalSegments    = flag.Bool("allow_colon_final_segments", false, "determines whether colons are permitted in the final segment of a path")
+	omitPackageDoc             = flag.Bool("omit_package_doc", false, "if true, no package comment will be included in the generated code")
 	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")
 	generateUnboundMethods     = flag.Bool("generate_unbound_methods", false, "generate proxy methods even for RPC methods that have no HttpRule annotation")
@@ -98,6 +99,7 @@ func main() {
 	reg.SetAllowDeleteBody(*allowDeleteBody)
 	reg.SetAllowRepeatedFieldsInBody(*allowRepeatedFieldsInBody)
 	reg.SetAllowColonFinalSegments(*allowColonFinalSegments)
+	reg.SetOmitPackageDoc(*omitPackageDoc)
 
 	if *warnOnUnboundMethods && *generateUnboundMethods {
 		glog.Warningf("Option warn_on_unbound_methods has no effect when generate_unbound_methods is used.")