doc(spanner): deprecate old MakeConnection() overloads (#10284)

Raise the disfavor for `ConnectionOptions` and `SessionPoolOptions`
arguments to `spanner::MakeConnection()` from @note to @deprecated.

Also removed some stale inclusions of `connection_options.h` and
`session_pool_options.h`.

Author: devbww

google/cloud/spanner/client.h

@@ -961,8 +961,8 @@ std::shared_ptr<spanner::Connection> MakeConnection(spanner::Database const& db,
  * The returned connection object should not be used directly, rather it should
  * be given to a `Client` instance, and methods should be invoked on `Client`.
  *
- * @note Prefer using the `MakeConnection()` overload that accepts
- *     `google::cloud::Options`.
+ * @deprecated Please use the `MakeConnection()` overload that accepts
+ *     `google::cloud::Options` instead.
  *
  * @see `Connection`
  *
@@ -979,8 +979,8 @@ std::shared_ptr<Connection> MakeConnection(
 /**
  * @copydoc MakeConnection(Database const&, ConnectionOptions const&, SessionPoolOptions)
  *
- * @note Prefer using the `MakeConnection()` overload that accepts
- *     `google::cloud::Options`.
+ * @deprecated Please use the `MakeConnection()` overload that accepts
+ *     `google::cloud::Options` instead.
  *
  * @param retry_policy override the default `RetryPolicy`, controls how long
  *     the returned `Connection` object retries requests on transient

google/cloud/spanner/internal/defaults.cc

@@ -73,7 +73,7 @@ Options DefaultOptions(Options opts) {
     }
   }
 
-  // Sets Spanner-specific options from session_pool_options.h
+  // Sets Spanner-specific session-pool options.
   auto& num_channels = opts.lookup<GrpcNumChannelsOption>();
   num_channels = (std::max)(num_channels, 1);
   if (!opts.has<spanner::SessionPoolMinSessionsOption>()) {

google/cloud/spanner/internal/defaults_test.cc

@@ -15,7 +15,6 @@
 #include "google/cloud/spanner/internal/defaults.h"
 #include "google/cloud/spanner/internal/session_pool.h"
 #include "google/cloud/spanner/options.h"
-#include "google/cloud/spanner/session_pool_options.h"
 #include "google/cloud/common_options.h"
 #include "google/cloud/grpc_options.h"
 #include "google/cloud/internal/compiler_info.h"

google/cloud/spanner/internal/metadata_spanner_stub_test.cc

@@ -15,6 +15,7 @@
 #include "google/cloud/spanner/internal/metadata_spanner_stub.h"
 #include "google/cloud/spanner/database.h"
 #include "google/cloud/spanner/testing/mock_spanner_stub.h"
+#include "google/cloud/common_options.h"
 #include "google/cloud/internal/api_client_header.h"
 #include "google/cloud/testing_util/status_matchers.h"
 #include "google/cloud/testing_util/validate_metadata.h"

google/cloud/spanner/internal/session_pool.h

@@ -21,7 +21,6 @@
 #include "google/cloud/spanner/internal/session.h"
 #include "google/cloud/spanner/internal/spanner_stub.h"
 #include "google/cloud/spanner/retry_policy.h"
-#include "google/cloud/spanner/session_pool_options.h"
 #include "google/cloud/spanner/version.h"
 #include "google/cloud/backoff_policy.h"
 #include "google/cloud/completion_queue.h"

google/cloud/spanner/internal/spanner_stub.h

@@ -15,7 +15,6 @@
 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_INTERNAL_SPANNER_STUB_H
 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_INTERNAL_SPANNER_STUB_H
 
-#include "google/cloud/spanner/connection_options.h"
 #include "google/cloud/spanner/database.h"
 #include "google/cloud/spanner/version.h"
 #include "google/cloud/completion_queue.h"

google/cloud/spanner/samples/samples.cc

@@ -21,7 +21,6 @@
 #include "google/cloud/spanner/admin/instance_admin_options.h"
 #include "google/cloud/spanner/backoff_policy.h"
 #include "google/cloud/spanner/backup.h"
-#include "google/cloud/spanner/connection_options.h"
 #include "google/cloud/spanner/create_instance_request_builder.h"
 #include "google/cloud/spanner/row.h"
 #include "google/cloud/spanner/testing/debug_log.h"  // TODO(#4758): remove