google-cloud-cpp Use `GOOGLE_CLOUD_CPP_DEPRECATED` for deprecated RPCs

RPCs can be annotated with option deprecated = true, e.g.:

https://github.com/googleapis/googleapis/blob/25d691b074e0b932e1c3f8a690ced8ddec8ae50e/google/container/v1/cluster_service.proto#L178-L194

For new libraries, we should not generate any RPCs that are deprecated, if necessary by adding them to the omit_rpcs list. For existing GA libraries we should generate a @deprecated Doxygen comment, and (most likely) add the GOOGLE_CLOUD_CPP_DEPRECATED annotation, though this has problems with builds using -Werror.

Mar 02 '22 18:03 coryan

For new libraries ... For existing GA libraries ...

Right ... which in turn requires some way to distinguish those cases. My only thought at the time was that any option deprecated = true RPC should be required to be listed in one of omit_rpcs (for new libraries) or a new "emit_rpcs" (for newly deprecated RPCs in existing libraries).

Mar 02 '22 19:03 devbww

We still want this, but do not have time.

Jul 28 '22 18:07 coryan

No time for this, to the backlog.

Jan 11 '23 19:01 coryan

@dbolduc points out in #10573 that we also need to be wary of deprecated message fields that appear in google.api.method_signature options, and hence in RPC overloads.

If the field is newly deprecated, we've probably previously released its overload, and so need to maintain that for backwards compatibility. And in order to know that, we need long-term memory like the emitted_rpcs and omitted_rpc config elements.

And still, if we decide to generate code for a deprecated RPC, or an overload using a deprecated field, we want to add an @deprecated Doxygen comment and the GOOGLE_CLOUD_CPP_DEPRECATED annotation.

Jan 13 '23 21:01 devbww

Aside: Note that the proto compiler already adds PROTOBUF_DEPRECATED (__attribute__((deprecated))) to the accessors for deprecated message fields.

Jan 14 '23 22:01 devbww