doc(spanner): mark obsolete Spanner options classes as deprecated (#1…

…2256) Mark the `spanner::${foo}Options` classes that are only used in the backwards-compatibility `spanner::Client` functions as deprecated. List the "Options" types that should be used in their place. Note: These are still also used when mocking a `spanner::Connection`.
googleapis · Jul 28, 2023 · e2d3220 · e2d3220
1 parent 8a7533a
commit e2d3220
Show file tree

Hide file tree

Showing 8 changed files with 82 additions and 8 deletions.
diff --git a/google/cloud/spanner/client_options.h b/google/cloud/spanner/client_options.h
@@ -27,6 +27,17 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /**
  * ClientOptions allows the caller to set a variety of options when
  * constructing a `Client` instance.
+ *
+ * @deprecated Use [`Options`](@ref google::cloud::Options) instead,
+ *     and set (as needed)
+ *     [`QueryOptimizerVersionOption`](
+ *     @ref google::cloud::spanner::QueryOptimizerVersionOption),
+ *     [`QueryOptimizerStatisticsPackageOption`](
+ *     @ref google::cloud::spanner::QueryOptimizerStatisticsPackageOption),
+ *     [`RequestPriorityOption`](
+ *     @ref google::cloud::spanner::RequestPriorityOption), or
+ *     [`RequestTagOption`](
+ *     @ref google::cloud::spanner::RequestTagOption).
  */
 class ClientOptions {
  public:

diff --git a/google/cloud/spanner/commit_options.h b/google/cloud/spanner/commit_options.h
@@ -29,6 +29,15 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /**
  * Set options on calls to `spanner::Client::Commit()`.
  *
+ * @deprecated Use [`Options`](@ref google::cloud::Options) instead,
+ *     and set (as needed)
+ *     [`CommitReturnStatsOption`](
+ *     @ref google::cloud::spanner::CommitReturnStatsOption),
+ *     [`RequestPriorityOption`](
+ *     @ref google::cloud::spanner::RequestPriorityOption), or
+ *     [`TransactionTagOption`](
+ *     @ref google::cloud::spanner::TransactionTagOption).
+ *
  * @par Example
  * @snippet samples.cc commit-options
  */

diff --git a/google/cloud/spanner/connection_options.h b/google/cloud/spanner/connection_options.h
@@ -27,10 +27,14 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /**
  * The traits to configure [`ConnectionOptions<T>`] for Cloud Spanner.
  *
- * @deprecated Use the options [`Options`](@ref google::cloud::Options) class
- * and set (as needed) [`EndpointOption`](@ref google::cloud::EndpointOption),
- * [`UserAgentProductsOption`](@ref google::cloud::UserAgentProductsOption),
- * and [`GrpcNumChannelsOption`](@ref google::cloud::GrpcNumChannelsOption).
+ * @deprecated Use [`Options`](@ref google::cloud::Options) instead,
+ *     and set (as needed)
+ *     [`EndpointOption`](
+ *     @ref google::cloud::EndpointOption),
+ *     [`UserAgentProductsOption`](
+ *     @ref google::cloud::UserAgentProductsOption), or
+ *     [`GrpcNumChannelsOption`](
+ *     @ref google::cloud::GrpcNumChannelsOption).
  *
  * [`ConnectionOptions<T>`]: @ref google::cloud::ConnectionOptions
  */

diff --git a/google/cloud/spanner/partition_options.h b/google/cloud/spanner/partition_options.h
@@ -30,6 +30,15 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 /**
  * Options passed to `Client::PartitionRead` or `Client::PartitionQuery`.
  *
+ * @deprecated Use [`Options`](@ref google::cloud::Options) instead,
+ *     and set (as needed)
+ *     [`PartitionSizeOption`](
+ *     @ref google::cloud::spanner::PartitionSizeOption),
+ *     [`PartitionsMaximumOption`](
+ *     @ref google::cloud::spanner::PartitionsMaximumOption), or
+ *     [`PartitionDataBoostOption`](
+ *     @ref google::cloud::spanner::PartitionDataBoostOption).
+ *
  * See documentation in [spanner.proto][spanner-proto].
  *
  * [spanner-proto]:

diff --git a/google/cloud/spanner/query_options.h b/google/cloud/spanner/query_options.h
@@ -31,6 +31,17 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
  * These QueryOptions allow users to configure features about how their SQL
  * queries executes on the server.
  *
+ * @deprecated Use [`Options`](@ref google::cloud::Options) instead,
+ *     and set (as needed)
+ *     [`QueryOptimizerVersionOption`](
+ *     @ref google::cloud::spanner::QueryOptimizerVersionOption),
+ *     [`QueryOptimizerStatisticsPackageOption`](
+ *     @ref google::cloud::spanner::QueryOptimizerStatisticsPackageOption),
+ *     [`RequestPriorityOption`](
+ *     @ref google::cloud::spanner::RequestPriorityOption), or
+ *     [`RequestTagOption`](
+ *     @ref google::cloud::spanner::RequestTagOption).
+ *
  * @see https://cloud.google.com/spanner/docs/reference/rest/v1/QueryOptions
  * @see http://cloud/spanner/docs/query-optimizer/manage-query-optimizer
  */

diff --git a/google/cloud/spanner/read_options.h b/google/cloud/spanner/read_options.h
@@ -28,7 +28,20 @@ namespace cloud {
 namespace spanner {
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 
-/// Options passed to `Client::Read` or `Client::PartitionRead`.
+/**
+ * Options passed to `Client::Read` or `Client::PartitionRead`.
+ *
+ * @deprecated Use [`Options`](@ref google::cloud::Options) instead,
+ *     and set (as needed)
+ *     [`ReadIndexNameOption`](
+ *     @ref google::cloud::spanner::ReadIndexNameOption),
+ *     [`ReadRowLimitOption`](
+ *     @ref google::cloud::spanner::ReadRowLimitOption),
+ *     [`RequestPriorityOption`](
+ *     @ref google::cloud::spanner::RequestPriorityOption), or
+ *     [`RequestTagOption`](
+ *     @ref google::cloud::spanner::RequestTagOption).
+ */
 struct ReadOptions {
   /**
    * If non-empty, the name of an index on a database table. This index is

diff --git a/google/cloud/spanner/session_pool_options.h b/google/cloud/spanner/session_pool_options.h
@@ -55,6 +55,23 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
  *     also possible to configure the client to fail a request when the session
  *     pool is exhausted.
  *
+ * @deprecated Use [`Options`](@ref google::cloud::Options) instead,
+ *     and set (as needed)
+ *     [`GrpcNumChannelsOption`](
+ *     @ref google::cloud::GrpcNumChannelsOption),
+ *     [`SessionPoolMinSessionsOption`](
+ *     @ref google::cloud::spanner::SessionPoolMinSessionsOption),
+ *     [`SessionPoolMaxSessionsPerChannelOption`](
+ *     @ref google::cloud::spanner::SessionPoolMaxSessionsPerChannelOption),
+ *     [`SessionPoolMaxIdleSessionsOption`](
+ *     @ref google::cloud::spanner::SessionPoolMaxIdleSessionsOption),
+ *     [`SessionPoolActionOnExhaustionOption`](
+ *     @ref google::cloud::spanner::SessionPoolActionOnExhaustionOption),
+ *     [`SessionPoolKeepAliveIntervalOption`](
+ *     @ref google::cloud::spanner::SessionPoolKeepAliveIntervalOption), or
+ *     [`SessionPoolLabelsOption`](
+ *     @ref google::cloud::spanner::SessionPoolLabelsOption).
+ *
  * [spanner-sessions-doc]: https://cloud.google.com/spanner/docs/sessions
  */
 class SessionPoolOptions {

diff --git a/google/cloud/spanner/tracing_options.h b/google/cloud/spanner/tracing_options.h
@@ -27,9 +27,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
  * The configuration parameters for RPC/protobuf tracing.
  *
  * The default options are:
- *   single_line_mode=on
- *   use_short_repeated_primitives=on
- *   truncate_string_field_longer_than=128
+ *   - single_line_mode=on
+ *   - use_short_repeated_primitives=on
+ *   - truncate_string_field_longer_than=128
  */
 using TracingOptions = ::google::cloud::TracingOptions;