java generator: mark all generated classes and interfaces with javax.annotation.Generated

[estekhin]

javax.annotation.Generated exists since Java 6 (relevant javadoc) so it should be safe to generate source code that contains it. The presence of this annotation has no impact on the runtime characteristics of the annotated classes.

When this annotation is present it greatly helps in configuration of different tools related to code analysis, tests and tests coverage.

Both the outer Java class and all inner builder and message classes and interfaces should be annotated with javax.annotation.Generated.

[froque]

it seems that there is already an option for this: --java_opt=annotate_code but it is not documented in the help text

[liujisi]

Annotating generated code is on our radar. There are several different proposals (for different use case) that we haven't reached consensus yet (e.g. whether to use custom annotations, whether to use runtime retention etc)

[sergei-ivanov]

I've just played around with the undocumented --java_opt=annotate_code.

Obviously, it only works in proto3, and in the latest versions only (fails with protoc 3.1.0). That's fair enough though (especially as it is not officially supported).

It looks like when the option is specified, only top-level classes and interfaces are being annotated. java_multiple_files option only affects it in a way that more top-level (annotated) classes are being produced, but any nested classes or interfaces are still not annotated. I am pretty sure that most of the static analysis tools and IDEs will not automatically apply/propagate @Generated from the outer class to the inner classes.

protoc also generates a binary xxx.java.pb.meta file for each generated xxx.java class. The purpose of these files is unclear and there is no way to suppress their generation either.

I have also tried adding option annotate_code = true; to the proto file, but that has been rejected as an invalid option by the compiler. Looking at the source code of protoc confirmed that only command line option is supported at the moment. I think an option at the proto source file level this might be a good alternative way of controlling the annotations generation, perhaps in addition to the command line option.

I hope the kind folks at Google are going to provide a bit more clarity in the due course.

[xfxyjwf]

@sergei-ivanov I believe the option --java_opt=annotate_code is not meant to be published. It was introduced for a Google internal source code indexing pipeline and not designed for public consumption.

[froque]

People seem to want this feature, I now I do. There is already the code to enable it. Why not make it public?

[dimo414]

@pherl what's the concern with adding @javax.annotation.Generated? I can understand also wanting to add some custom annotation and needing to figure out its retention policy, but many tools rely on the javax annotation, and it exists specifically for this purpose.

[liujisi]

There were several teams asking for annotations but with different requirement, e.g. runtime retention vs compile time retention; annotation with type information. All of those will affect how we should annotate the classes. There is also on-going experimental java runtime developement work that uses annotations. I think after the new runtime work is done, we can revisit the annotation issue.