Add --omit_package_doc flag

[RJPercival]

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).

For an example of a package where this would be useful, see https://pkg.go.dev/github.com/google/trillian?tab=doc.

[codecov-io]

Codecov Report

Merging #1103 into master will decrease coverage by 0.07%.
The diff coverage is 0%.

@@            Coverage Diff             @@
##           master    #1103      +/-   ##
==========================================
- Coverage   53.89%   53.82%   -0.08%     
==========================================
  Files          42       42              
  Lines        4180     4186       +6     
==========================================
  Hits         2253     2253              
- Misses       1681     1686       +5     
- Partials      246      247       +1

Impacted Files	Coverage Δ
protoc-gen-grpc-gateway/gengateway/template.go	80.58% <ø> (ø)	⬆️
protoc-gen-grpc-gateway/gengateway/generator.go	37.86% <0%> (-0.75%)	⬇️
protoc-gen-grpc-gateway/descriptor/registry.go	56.77% <0%> (-0.98%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 50c55a9...4179579. Read the comment docs.

[RJPercival]

I haven't added any tests for this yet, since I want to confirm it's something that could be added first (and I'm not sure this is the best way to implement it - I'm not familiar with the codebase). Please let me know whether it's worth completing this PR.

[johanbrandhorst]

Hi Rob! Thanks for taking an interest in this project. Generally these generated files go into the same folder as the generated go files, and nothing else. Help me understand, are you saying that your use case includes manually adding package comments to this otherwise generated package?

[RJPercival]

In the case of https://github.com/google/trillian, the generated grpc-gateway code lives in the root directory, alongside the generated protobuf code. This has the unfortunate effect of making the subtitle of "github.com/google/trillian" on https://pkg.go.dev/search?q=trillian show "Package trillian is a reverse proxy." This is misleading, since it suggests that Trillian is a reverse proxy, when it isn't (that's just what the grpc-gateway code does, and it's mostly irrelevant to users). We'd prefer to add a doc.go file to our root directory and write our top-level package comment there, but right now there's no way to suppress the grpc-gateway package comment. We could remove the package comment after code generation, but that'd be onerous (and clash with our presubmit checks that ensure checked-in generated code is pristine).

[RJPercival]

As an example, gomock has a --write_package_comment flag that does what we want for its generated code. We'd just like an equivalent for grpc-gateway.

[johanbrandhorst]

Thanks for the explanation, I think what's confusing me is why the generated code lives in the root of the repo (and thus producing this confusing and misleading documentation for the root package). Not saying I'm opposed to merging this change, but why can't you move the generated code to another directory?

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[RJPercival]

In the end we've just decided to remove our use of grpc-gateway entirely.