feat(generator): document details about *Client (#7673)

Customers often wonder about the performance, thread-safety, and
connection pooling in our `*Client` classes. This changes the generator
to include this information in the generated code.

generator/integration_tests/golden/golden_kitchen_sink_client.h

@@ -44,6 +44,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// tokens, OpenID Connect ID tokens, self-signed JSON Web Tokens (JWTs), and
 /// more.
 ///
+/// @par Equality
+///
+/// Instances of this class created via copy-construction or copy-assignment
+/// always compare equal. Instances created with equal
+/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare
+/// equal share the same underlying resources.
+///
+/// @par Performance
+///
+/// Creating a new instance of this class is a relatively expensive operation,
+/// new objects establish new connections to the service. In contrast,
+/// copy-construction, move-construction, and the corresponding assignment
+/// operations are relatively efficient as the copies share all underlying
+/// resources.
+///
+/// @par Thread Safety
+///
+/// Concurrent access to different instances of this class, even if they compare
+/// equal, is guaranteed to work. Two or more threads operating on the same
+/// instance of this class is not guaranteed to work. Since copy-construction
+/// and move-construction is a relatively efficient operation, consider using
+/// such a copy when using this class from multiple threads.
+///
 class GoldenKitchenSinkClient {
  public:
   explicit GoldenKitchenSinkClient(std::shared_ptr<GoldenKitchenSinkConnection> connection);

generator/integration_tests/golden/golden_thing_admin_client.h

@@ -42,6 +42,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// databases. It can be also used to create, delete and list backups for a
 /// database and to restore from an existing backup.
 ///
+/// @par Equality
+///
+/// Instances of this class created via copy-construction or copy-assignment
+/// always compare equal. Instances created with equal
+/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare
+/// equal share the same underlying resources.
+///
+/// @par Performance
+///
+/// Creating a new instance of this class is a relatively expensive operation,
+/// new objects establish new connections to the service. In contrast,
+/// copy-construction, move-construction, and the corresponding assignment
+/// operations are relatively efficient as the copies share all underlying
+/// resources.
+///
+/// @par Thread Safety
+///
+/// Concurrent access to different instances of this class, even if they compare
+/// equal, is guaranteed to work. Two or more threads operating on the same
+/// instance of this class is not guaranteed to work. Since copy-construction
+/// and move-construction is a relatively efficient operation, consider using
+/// such a copy when using this class from multiple threads.
+///
 class GoldenThingAdminClient {
  public:
   explicit GoldenThingAdminClient(std::shared_ptr<GoldenThingAdminConnection> connection);

generator/internal/descriptor_utils.cc

@@ -292,7 +292,31 @@ std::string FormatClassCommentsFromServiceComments(
                    absl::StrReplaceAll(
                        ChompByValue(service_source_location.leading_comments),
                        {{"\n\n", "\n///\n/// "}, {"\n", "\n/// "}}),
-                   "\n///");
+                   R"""(
+///
+/// @par Equality
+///
+/// Instances of this class created via copy-construction or copy-assignment
+/// always compare equal. Instances created with equal
+/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare
+/// equal share the same underlying resources.
+///
+/// @par Performance
+///
+/// Creating a new instance of this class is a relatively expensive operation,
+/// new objects establish new connections to the service. In contrast,
+/// copy-construction, move-construction, and the corresponding assignment
+/// operations are relatively efficient as the copies share all underlying
+/// resources.
+///
+/// @par Thread Safety
+///
+/// Concurrent access to different instances of this class, even if they compare
+/// equal, is guaranteed to work. Two or more threads operating on the same
+/// instance of this class is not guaranteed to work. Since copy-construction
+/// and move-construction is a relatively efficient operation, consider using
+/// such a copy when using this class from multiple threads.
+///)""");
   return absl::StrReplaceAll(doxygen_formatted_comments, {{"///  ", "/// "}});
 }
 

generator/internal/descriptor_utils_test.cc

@@ -183,7 +183,7 @@ TEST_P(CreateServiceVarsTest, KeySetCorrectly) {
       {std::make_pair("product_path", "google/cloud/frobber/")});
   auto iter = service_vars_.find(GetParam().first);
   EXPECT_TRUE(iter != service_vars_.end());
-  EXPECT_EQ(iter->second, GetParam().second);
+  EXPECT_THAT(iter->second, HasSubstr(GetParam().second));
 }
 
 INSTANTIATE_TEST_SUITE_P(

google/cloud/bigquery/bigquery_read_client.h

@@ -36,6 +36,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 ///
 /// The Read API can be used to read data from BigQuery.
 ///
+/// @par Equality
+///
+/// Instances of this class created via copy-construction or copy-assignment
+/// always compare equal. Instances created with equal
+/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare
+/// equal share the same underlying resources.
+///
+/// @par Performance
+///
+/// Creating a new instance of this class is a relatively expensive operation,
+/// new objects establish new connections to the service. In contrast,
+/// copy-construction, move-construction, and the corresponding assignment
+/// operations are relatively efficient as the copies share all underlying
+/// resources.
+///
+/// @par Thread Safety
+///
+/// Concurrent access to different instances of this class, even if they compare
+/// equal, is guaranteed to work. Two or more threads operating on the same
+/// instance of this class is not guaranteed to work. Since copy-construction
+/// and move-construction is a relatively efficient operation, consider using
+/// such a copy when using this class from multiple threads.
+///
 class BigQueryReadClient {
  public:
   explicit BigQueryReadClient(

google/cloud/iam/iam_client.h

@@ -54,6 +54,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// * Check which roles you can grant for a specific resource
 /// * Lint, or validate, condition expressions in an IAM policy
 ///
+/// @par Equality
+///
+/// Instances of this class created via copy-construction or copy-assignment
+/// always compare equal. Instances created with equal
+/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare
+/// equal share the same underlying resources.
+///
+/// @par Performance
+///
+/// Creating a new instance of this class is a relatively expensive operation,
+/// new objects establish new connections to the service. In contrast,
+/// copy-construction, move-construction, and the corresponding assignment
+/// operations are relatively efficient as the copies share all underlying
+/// resources.
+///
+/// @par Thread Safety
+///
+/// Concurrent access to different instances of this class, even if they compare
+/// equal, is guaranteed to work. Two or more threads operating on the same
+/// instance of this class is not guaranteed to work. Since copy-construction
+/// and move-construction is a relatively efficient operation, consider using
+/// such a copy when using this class from multiple threads.
+///
 class IAMClient {
  public:
   explicit IAMClient(std::shared_ptr<IAMConnection> connection);

google/cloud/iam/iam_credentials_client.h

@@ -43,6 +43,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// tokens, OpenID Connect ID tokens, self-signed JSON Web Tokens (JWTs), and
 /// more.
 ///
+/// @par Equality
+///
+/// Instances of this class created via copy-construction or copy-assignment
+/// always compare equal. Instances created with equal
+/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare
+/// equal share the same underlying resources.
+///
+/// @par Performance
+///
+/// Creating a new instance of this class is a relatively expensive operation,
+/// new objects establish new connections to the service. In contrast,
+/// copy-construction, move-construction, and the corresponding assignment
+/// operations are relatively efficient as the copies share all underlying
+/// resources.
+///
+/// @par Thread Safety
+///
+/// Concurrent access to different instances of this class, even if they compare
+/// equal, is guaranteed to work. Two or more threads operating on the same
+/// instance of this class is not guaranteed to work. Since copy-construction
+/// and move-construction is a relatively efficient operation, consider using
+/// such a copy when using this class from multiple threads.
+///
 class IAMCredentialsClient {
  public:
   explicit IAMCredentialsClient(

google/cloud/logging/logging_service_v2_client.h

@@ -35,6 +35,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 ///
 /// Service for ingesting and querying logs.
 ///
+/// @par Equality
+///
+/// Instances of this class created via copy-construction or copy-assignment
+/// always compare equal. Instances created with equal
+/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare
+/// equal share the same underlying resources.
+///
+/// @par Performance
+///
+/// Creating a new instance of this class is a relatively expensive operation,
+/// new objects establish new connections to the service. In contrast,
+/// copy-construction, move-construction, and the corresponding assignment
+/// operations are relatively efficient as the copies share all underlying
+/// resources.
+///
+/// @par Thread Safety
+///
+/// Concurrent access to different instances of this class, even if they compare
+/// equal, is guaranteed to work. Two or more threads operating on the same
+/// instance of this class is not guaranteed to work. Since copy-construction
+/// and move-construction is a relatively efficient operation, consider using
+/// such a copy when using this class from multiple threads.
+///
 class LoggingServiceV2Client {
  public:
   explicit LoggingServiceV2Client(

google/cloud/pubsublite/admin_client.h

@@ -37,6 +37,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// subscriptions, such creating, listing, and deleting topics and
 /// subscriptions.
 ///
+/// @par Equality
+///
+/// Instances of this class created via copy-construction or copy-assignment
+/// always compare equal. Instances created with equal
+/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare
+/// equal share the same underlying resources.
+///
+/// @par Performance
+///
+/// Creating a new instance of this class is a relatively expensive operation,
+/// new objects establish new connections to the service. In contrast,
+/// copy-construction, move-construction, and the corresponding assignment
+/// operations are relatively efficient as the copies share all underlying
+/// resources.
+///
+/// @par Thread Safety
+///
+/// Concurrent access to different instances of this class, even if they compare
+/// equal, is guaranteed to work. Two or more threads operating on the same
+/// instance of this class is not guaranteed to work. Since copy-construction
+/// and move-construction is a relatively efficient operation, consider using
+/// such a copy when using this class from multiple threads.
+///
 class AdminServiceClient {
  public:
   explicit AdminServiceClient(

google/cloud/secretmanager/secret_manager_client.h

@@ -41,6 +41,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// * [Secret][google.cloud.secretmanager.v1.Secret]
 /// * [SecretVersion][google.cloud.secretmanager.v1.SecretVersion]
 ///
+/// @par Equality
+///
+/// Instances of this class created via copy-construction or copy-assignment
+/// always compare equal. Instances created with equal
+/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare
+/// equal share the same underlying resources.
+///
+/// @par Performance
+///
+/// Creating a new instance of this class is a relatively expensive operation,
+/// new objects establish new connections to the service. In contrast,
+/// copy-construction, move-construction, and the corresponding assignment
+/// operations are relatively efficient as the copies share all underlying
+/// resources.
+///
+/// @par Thread Safety
+///
+/// Concurrent access to different instances of this class, even if they compare
+/// equal, is guaranteed to work. Two or more threads operating on the same
+/// instance of this class is not guaranteed to work. Since copy-construction
+/// and move-construction is a relatively efficient operation, consider using
+/// such a copy when using this class from multiple threads.
+///
 class SecretManagerServiceClient {
  public:
   explicit SecretManagerServiceClient(

google/cloud/spanner/admin/database_admin_client.h

@@ -42,6 +42,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// databases. It can be also used to create, delete and list backups for a
 /// database and to restore from an existing backup.
 ///
+/// @par Equality
+///
+/// Instances of this class created via copy-construction or copy-assignment
+/// always compare equal. Instances created with equal
+/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare
+/// equal share the same underlying resources.
+///
+/// @par Performance
+///
+/// Creating a new instance of this class is a relatively expensive operation,
+/// new objects establish new connections to the service. In contrast,
+/// copy-construction, move-construction, and the corresponding assignment
+/// operations are relatively efficient as the copies share all underlying
+/// resources.
+///
+/// @par Thread Safety
+///
+/// Concurrent access to different instances of this class, even if they compare
+/// equal, is guaranteed to work. Two or more threads operating on the same
+/// instance of this class is not guaranteed to work. Since copy-construction
+/// and move-construction is a relatively efficient operation, consider using
+/// such a copy when using this class from multiple threads.
+///
 class DatabaseAdminClient {
  public:
   explicit DatabaseAdminClient(

google/cloud/spanner/admin/instance_admin_client.h

@@ -58,6 +58,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// instance resources, fewer resources are available for other
 /// databases in that instance, and their performance may suffer.
 ///
+/// @par Equality
+///
+/// Instances of this class created via copy-construction or copy-assignment
+/// always compare equal. Instances created with equal
+/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare
+/// equal share the same underlying resources.
+///
+/// @par Performance
+///
+/// Creating a new instance of this class is a relatively expensive operation,
+/// new objects establish new connections to the service. In contrast,
+/// copy-construction, move-construction, and the corresponding assignment
+/// operations are relatively efficient as the copies share all underlying
+/// resources.
+///
+/// @par Thread Safety
+///
+/// Concurrent access to different instances of this class, even if they compare
+/// equal, is guaranteed to work. Two or more threads operating on the same
+/// instance of this class is not guaranteed to work. Since copy-construction
+/// and move-construction is a relatively efficient operation, consider using
+/// such a copy when using this class from multiple threads.
+///
 class InstanceAdminClient {
  public:
   explicit InstanceAdminClient(

google/cloud/tasks/cloud_tasks_client.h

@@ -37,6 +37,29 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /// Cloud Tasks allows developers to manage the execution of background
 /// work in their applications.
 ///
+/// @par Equality
+///
+/// Instances of this class created via copy-construction or copy-assignment
+/// always compare equal. Instances created with equal
+/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare
+/// equal share the same underlying resources.
+///
+/// @par Performance
+///
+/// Creating a new instance of this class is a relatively expensive operation,
+/// new objects establish new connections to the service. In contrast,
+/// copy-construction, move-construction, and the corresponding assignment
+/// operations are relatively efficient as the copies share all underlying
+/// resources.
+///
+/// @par Thread Safety
+///
+/// Concurrent access to different instances of this class, even if they compare
+/// equal, is guaranteed to work. Two or more threads operating on the same
+/// instance of this class is not guaranteed to work. Since copy-construction
+/// and move-construction is a relatively efficient operation, consider using
+/// such a copy when using this class from multiple threads.
+///
 class CloudTasksClient {
  public:
   explicit CloudTasksClient(std::shared_ptr<CloudTasksConnection> connection);