Generate @Deprecated annotations

[timostamm]

This updates the plugin protoc-gen-connect-kotlin to generate annotations for deprecated elements. Closes #333.

If an RPC is marked deprecated with the option deprecated = true, the corresponding member of the generated client interface and implementation is annotated with:

@Deprecated("The method is deprecated in the Protobuf source file.")

Deprecating entire services is supported as well. If deprecated = true is set on a service, the generated client interface and implementation is annotated with:

@Deprecated("The service is deprecated in the Protobuf source file.")

For good measure, deprecating Protobuf files is supported as well. Because kotlin.Deprecated is not applicable to files, we annotate every client interface and implementation generated from the file:

@Deprecated("The Protobuf source file that defines this service is deprecated.")

[jhump]

LGTM. Small (non-blocking) suggestion on deprecation message wording. Feel free to accept suggestions or not.

[jhump]

Looks like you may need to add the "ignore deprecations" annotation at the top of the generated files, like the base protoc plugins do, to fix the CI build issue.

[erawhctim]

@timostamm thanks for tackling this!

One question: if a comment exists on the deprecation option in the proto file, or on an rpc definition, would it be feasible to surface that comment as part of the Deprecated annotation in the generated Kotlin code?

Ideally, the proto spec itself would support some kind of deprecation message field to define this in a more official way, but I can very easily imagine our developers adding a comment to explain the deprecation and/or point to a replacement, non-deprecated field/rpc call. If there's a way we can include that context in Kotlin, that would be a huge win. Is that possible with what we have today?

[timostamm]

Looks like you may need to add the "ignore deprecations" annotation at the top of the generated files, like the base protoc plugins do, to fix the CI build issue.

Generating @file:Suppress("DEPRECATION") allows to compile the file without warning, but using the deprecated code elsewhere will still raise a warning. This works out well. Done in eec519e.

[timostamm]

@erawhctim, I don't even know a language from the top of my head that supports deprecations, but doesn't support deprecation messages. Unfortunately, the option for deprecating elements in Protobuf is typed as a boolean (source), and doesn't allow users or us to provide a description.

I think the most reasonable approach for now is to add a comment in the Protobuf source when you set deprecated = true. The comments will show up as KDoc.

[jhump]

would it be feasible to surface that comment as part of the Deprecated annotation in the generated Kotlin code?

Unfortunately, plugins do not have access to such comments.

Plugins must inspect a file descriptor's "source code info" to find comments. While "spans" (the location of an element in the source file) are generated for nearly everything, comments are only retained for complete declarations. The field itself is a complete declaration (so it's leading and trailing comments are preserved). But comments for elements inside the field -- like individual options inside the [...] -- are not retained in source code info and thus not available to plugins.