From 64751ac1e81fe902b164e9a4b63ea35c6b51cccb Mon Sep 17 00:00:00 2001 From: Greg Miller <9447643+devjgm@users.noreply.github.com> Date: Thu, 14 Oct 2021 07:07:37 -0400 Subject: [PATCH 1/2] doc: remove inline namespace from doxygen Fixes: #7453 With this change, our Doxygen documentation will no longer make any mention of our inline namespace for versioning, thus the docs will be accurately reflecting what we actually want customers to type. This PR removes all references to `omit_this_inline_ns`. --- CHANGELOG.md | 16 +++++++++ cmake/GoogleCloudCppCommon.cmake | 5 ++- .../doc/bigtable-hello-instance-admin.dox | 22 ++++++------ .../doc/bigtable-hello-table-admin.dox | 32 ++++++++--------- .../bigtable/doc/bigtable-hello-world.dox | 28 +++++++-------- google/cloud/bigtable/instance_admin.h | 10 +++--- google/cloud/bigtable/table.h | 10 +++--- google/cloud/bigtable/table_admin.h | 10 +++--- google/cloud/doc/common-main.dox | 15 ++++---- google/cloud/pubsub/mocks/mock_ack_handler.h | 3 +- .../pubsub/mocks/mock_publisher_connection.h | 3 +- .../mocks/mock_schema_admin_connection.h | 3 +- .../pubsub/mocks/mock_subscriber_connection.h | 3 +- .../mock_subscription_admin_connection.h | 3 +- .../mocks/mock_topic_admin_connection.h | 3 +- google/cloud/pubsub/publisher.h | 16 ++++----- google/cloud/pubsub/schema_admin_client.h | 6 ++-- google/cloud/pubsub/subscriber.h | 16 ++++----- .../cloud/pubsub/subscription_admin_client.h | 6 ++-- google/cloud/pubsub/topic_admin_client.h | 6 ++-- google/cloud/spanner/doc/spanner-main.dox | 10 +++--- google/cloud/storage/client.h | 33 +++++++----------- google/cloud/storage/doc/storage-main.dox | 34 +++++++++---------- google/cloud/storage/doc/storage-mocking.dox | 10 +++--- 24 files changed, 143 insertions(+), 160 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1fcadb0ac7832..153dcaac5fb29 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -69,6 +69,22 @@ ## v1.33.0 - TBD +**ATTENTION**: Users should generally **NOT** spell the name of our versioned +inline namespace in their code, as doing so will tightly couple your code to a +specific version of our library and will make upgrades more difficult for you. +Previously, this version was `v1` (but it will change in the future), and so +you may have some code that references, say, ~`google::cloud::v1::Status`~ +(WRONG) and you should instead prefer `google::cloud::Status` (omit the +versioned inline namespace name). + +Our Doxygen documentation (e.g. [Storage docs][storage-dox-link]) was +incorrectly showing the versioned inline namespace name for our symbols, +implicitly suggesting that users should spell this inline namespace in their +own code. This mistake was fixed and our Doxygen documentation no longer shows +the versioned inline namespace name. + +[storage-dox-link]: https://googleapis.dev/cpp/google-cloud-storage/latest/ + ## v1.32.1 - 2021-10 ### [Pub/Sub](https://github.com/googleapis/google-cloud-cpp/blob/main/google/cloud/pubsub/README.md) diff --git a/cmake/GoogleCloudCppCommon.cmake b/cmake/GoogleCloudCppCommon.cmake index 334f2fc196eb3..c309169bf00e4 100644 --- a/cmake/GoogleCloudCppCommon.cmake +++ b/cmake/GoogleCloudCppCommon.cmake @@ -80,9 +80,8 @@ elseif (GOOGLE_CLOUD_CPP_GENERATE_DOXYGEN) "GOOGLE_CLOUD_CPP_IAM_DEPRECATED(x)=" "GOOGLE_CLOUD_CPP_BIGTABLE_IAM_DEPRECATED(x)=" "GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED(x)=" - "GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN=inline namespace omit_this_inline_ns {" - "GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END=}" - "GOOGLE_CLOUD_CPP_NS=omit_this_inline_ns") + "GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN=" + "GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END=") set(DOXYGEN_HTML_TIMESTAMP YES) set(DOXYGEN_STRIP_FROM_INC_PATH "${PROJECT_SOURCE_DIR}") set(DOXYGEN_SHOW_USED_FILES NO) diff --git a/google/cloud/bigtable/doc/bigtable-hello-instance-admin.dox b/google/cloud/bigtable/doc/bigtable-hello-instance-admin.dox index a8bc772d16b4c..f329c84e3dd41 100644 --- a/google/cloud/bigtable/doc/bigtable-hello-instance-admin.dox +++ b/google/cloud/bigtable/doc/bigtable-hello-instance-admin.dox @@ -114,17 +114,17 @@ Here is the full example @snippet bigtable_hello_instance_admin.cc all code -[InstanceAdmin]: @ref google::cloud::bigtable::omit_this_inline_ns::InstanceAdmin -[InstanceAdmin-CreateInstance]: @ref google::cloud::bigtable::omit_this_inline_ns::InstanceAdmin::CreateInstance() -[InstanceAdmin-ListInstances]: @ref google::cloud::bigtable::omit_this_inline_ns::InstanceAdmin::ListInstances() -[InstanceAdmin-GetInstance]: @ref google::cloud::bigtable::omit_this_inline_ns::InstanceAdmin::GetInstance() -[InstanceAdmin-DeleteInstance]: @ref google::cloud::bigtable::omit_this_inline_ns::InstanceAdmin::DeleteInstance() -[InstanceAdmin-CreateCluster]: @ref google::cloud::bigtable::omit_this_inline_ns::InstanceAdmin::CreateCluster() -[InstanceAdmin-GetCluster]: @ref google::cloud::bigtable::omit_this_inline_ns::InstanceAdmin::GetCluster() -[InstanceAdmin-UpdateCluster]: @ref google::cloud::bigtable::omit_this_inline_ns::InstanceAdmin::UpdateCluster() -[InstanceAdmin-DeleteCluster]: @ref google::cloud::bigtable::omit_this_inline_ns::InstanceAdmin::DeleteCluster() -[InstanceAdmin-ListClusters]: @ref google::cloud::bigtable::omit_this_inline_ns::InstanceAdmin::ListClusters() -[InstanceConfig]: @ref google::cloud::bigtable::omit_this_inline_ns::InstanceConfig +[InstanceAdmin]: @ref google::cloud::bigtable::InstanceAdmin +[InstanceAdmin-CreateInstance]: @ref google::cloud::bigtable::InstanceAdmin::CreateInstance() +[InstanceAdmin-ListInstances]: @ref google::cloud::bigtable::InstanceAdmin::ListInstances() +[InstanceAdmin-GetInstance]: @ref google::cloud::bigtable::InstanceAdmin::GetInstance() +[InstanceAdmin-DeleteInstance]: @ref google::cloud::bigtable::InstanceAdmin::DeleteInstance() +[InstanceAdmin-CreateCluster]: @ref google::cloud::bigtable::InstanceAdmin::CreateCluster() +[InstanceAdmin-GetCluster]: @ref google::cloud::bigtable::InstanceAdmin::GetCluster() +[InstanceAdmin-UpdateCluster]: @ref google::cloud::bigtable::InstanceAdmin::UpdateCluster() +[InstanceAdmin-DeleteCluster]: @ref google::cloud::bigtable::InstanceAdmin::DeleteCluster() +[InstanceAdmin-ListClusters]: @ref google::cloud::bigtable::InstanceAdmin::ListClusters() +[InstanceConfig]: @ref google::cloud::bigtable::InstanceConfig [ListInstancesResponse-proto]: https://cloud.google.com/bigtable/docs/reference/admin/rpc/google.bigtable.admin.v2#google.bigtable.admin.v2.ListInstancesResponse [ListClustersResponse-proto]: https://cloud.google.com/bigtable/docs/reference/admin/rpc/google.bigtable.admin.v2#google.bigtable.admin.v2.ListClustersResponse diff --git a/google/cloud/bigtable/doc/bigtable-hello-table-admin.dox b/google/cloud/bigtable/doc/bigtable-hello-table-admin.dox index d9a1f6d33d476..79c30731a07c3 100644 --- a/google/cloud/bigtable/doc/bigtable-hello-table-admin.dox +++ b/google/cloud/bigtable/doc/bigtable-hello-table-admin.dox @@ -122,22 +122,22 @@ Here is the full example @snippet bigtable_hello_table_admin.cc all code -[GcRule]: @ref google::cloud::bigtable::omit_this_inline_ns::GcRule -[GcRule-MaxAge]: @ref google::cloud::bigtable::omit_this_inline_ns::GcRule::MaxAge() -[GcRule-MaxNumVersions]: @ref google::cloud::bigtable::omit_this_inline_ns::GcRule::MaxNumVersions() -[GcRule-Union]: @ref google::cloud::bigtable::omit_this_inline_ns::GcRule::Union() -[GcRule-Intersection]: @ref google::cloud::bigtable::omit_this_inline_ns::GcRule::Intersection() -[ColumnFamilyModification-Create]: @ref google::cloud::bigtable::omit_this_inline_ns::ColumnFamilyModification::Create() -[ColumnFamilyModification-Update]: @ref google::cloud::bigtable::omit_this_inline_ns::ColumnFamilyModification::Update() -[ColumnFamilyModification-Drop]: @ref google::cloud::bigtable::omit_this_inline_ns::ColumnFamilyModification::Drop() -[TableAdmin]: @ref google::cloud::bigtable::omit_this_inline_ns::TableAdmin -[TableAdmin-CreateTable]: @ref google::cloud::bigtable::omit_this_inline_ns::TableAdmin::CreateTable() -[TableAdmin-DeleteTable]: @ref google::cloud::bigtable::omit_this_inline_ns::TableAdmin::DeleteTable() -[TableAdmin-GetTable]: @ref google::cloud::bigtable::omit_this_inline_ns::TableAdmin::GetTable() -[TableAdmin-ListTables]: @ref google::cloud::bigtable::omit_this_inline_ns::TableAdmin::ListTables() -[TableAdmin-ModifyColumnFamilies]: @ref google::cloud::bigtable::omit_this_inline_ns::TableAdmin::ModifyColumnFamilies() -[TableAdmin-DropAllRows]: @ref google::cloud::bigtable::omit_this_inline_ns::TableAdmin::DropAllRows() -[TableAdmin-DropRowsByPrefix]: @ref google::cloud::bigtable::omit_this_inline_ns::TableAdmin::DropRowsByPrefix() +[GcRule]: @ref google::cloud::bigtable::GcRule +[GcRule-MaxAge]: @ref google::cloud::bigtable::GcRule::MaxAge() +[GcRule-MaxNumVersions]: @ref google::cloud::bigtable::GcRule::MaxNumVersions() +[GcRule-Union]: @ref google::cloud::bigtable::GcRule::Union() +[GcRule-Intersection]: @ref google::cloud::bigtable::GcRule::Intersection() +[ColumnFamilyModification-Create]: @ref google::cloud::bigtable::ColumnFamilyModification::Create() +[ColumnFamilyModification-Update]: @ref google::cloud::bigtable::ColumnFamilyModification::Update() +[ColumnFamilyModification-Drop]: @ref google::cloud::bigtable::ColumnFamilyModification::Drop() +[TableAdmin]: @ref google::cloud::bigtable::TableAdmin +[TableAdmin-CreateTable]: @ref google::cloud::bigtable::TableAdmin::CreateTable() +[TableAdmin-DeleteTable]: @ref google::cloud::bigtable::TableAdmin::DeleteTable() +[TableAdmin-GetTable]: @ref google::cloud::bigtable::TableAdmin::GetTable() +[TableAdmin-ListTables]: @ref google::cloud::bigtable::TableAdmin::ListTables() +[TableAdmin-ModifyColumnFamilies]: @ref google::cloud::bigtable::TableAdmin::ModifyColumnFamilies() +[TableAdmin-DropAllRows]: @ref google::cloud::bigtable::TableAdmin::DropAllRows() +[TableAdmin-DropRowsByPrefix]: @ref google::cloud::bigtable::TableAdmin::DropRowsByPrefix() [TableView-proto]: https://cloud.google.com/bigtable/docs/reference/admin/rpc/google.bigtable.admin.v2#google.bigtable.admin.v2.Table.View */ diff --git a/google/cloud/bigtable/doc/bigtable-hello-world.dox b/google/cloud/bigtable/doc/bigtable-hello-world.dox index 0da2256195c39..3d87da5169745 100644 --- a/google/cloud/bigtable/doc/bigtable-hello-world.dox +++ b/google/cloud/bigtable/doc/bigtable-hello-world.dox @@ -124,19 +124,19 @@ Here is the full example @snippet bigtable_hello_world.cc all code -[Filter]: @ref google::cloud::bigtable::omit_this_inline_ns::Filter -[InstanceAdmin]: @ref google::cloud::bigtable::omit_this_inline_ns::InstanceAdmin -[Mutation]: @ref google::cloud::bigtable::omit_this_inline_ns::Mutation -[Row]: @ref google::cloud::bigtable::omit_this_inline_ns::Row -[RowRange]: @ref google::cloud::bigtable::omit_this_inline_ns::RowRange -[RowSet]: @ref google::cloud::bigtable::omit_this_inline_ns::RowSet -[Table]: @ref google::cloud::bigtable::omit_this_inline_ns::Table -[Table-Apply]: @ref google::cloud::bigtable::omit_this_inline_ns::Table::Apply -[Table-BulkApply]: @ref google::cloud::bigtable::omit_this_inline_ns::Table::BulkApply -[Table-ReadRow]: @ref google::cloud::bigtable::omit_this_inline_ns::Table::ReadRow -[Table-ReadRows]: @ref google::cloud::bigtable::omit_this_inline_ns::Table::ReadRows -[TableAdmin]: @ref google::cloud::bigtable::omit_this_inline_ns::TableAdmin -[TableAdmin-CreateTable]: @ref google::cloud::bigtable::omit_this_inline_ns::TableAdmin::CreateTable -[TableAdmin-DeleteTable]: @ref google::cloud::bigtable::omit_this_inline_ns::TableAdmin::DeleteTable +[Filter]: @ref google::cloud::bigtable::Filter +[InstanceAdmin]: @ref google::cloud::bigtable::InstanceAdmin +[Mutation]: @ref google::cloud::bigtable::Mutation +[Row]: @ref google::cloud::bigtable::Row +[RowRange]: @ref google::cloud::bigtable::RowRange +[RowSet]: @ref google::cloud::bigtable::RowSet +[Table]: @ref google::cloud::bigtable::Table +[Table-Apply]: @ref google::cloud::bigtable::Table::Apply +[Table-BulkApply]: @ref google::cloud::bigtable::Table::BulkApply +[Table-ReadRow]: @ref google::cloud::bigtable::Table::ReadRow +[Table-ReadRows]: @ref google::cloud::bigtable::Table::ReadRows +[TableAdmin]: @ref google::cloud::bigtable::TableAdmin +[TableAdmin-CreateTable]: @ref google::cloud::bigtable::TableAdmin::CreateTable +[TableAdmin-DeleteTable]: @ref google::cloud::bigtable::TableAdmin::DeleteTable */ diff --git a/google/cloud/bigtable/instance_admin.h b/google/cloud/bigtable/instance_admin.h index fa923e716a5aa..384dc2a248505 100644 --- a/google/cloud/bigtable/instance_admin.h +++ b/google/cloud/bigtable/instance_admin.h @@ -60,10 +60,8 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN * the `ok()` member function in the `StatusOr` returns `true` then it * contains the expected result. Operations that do not return a value simply * return a `google::cloud::Status` indicating success or the details of the - * error Please consult the - * [`StatusOr` - * documentation](#google::cloud::omit_this_inline_ns::StatusOr) for more - * details. + * error Please consult the [`StatusOr` + * documentation](#google::cloud::StatusOr) for more details. * * @code * namespace cbt = google::cloud::bigtable; @@ -111,8 +109,8 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN * @see https://cloud.google.com/bigtable/docs/reference/service-apis-overview * for an overview of the underlying Cloud Bigtable API. * - * @see #google::cloud::omit_this_inline_ns::StatusOr for a description of the - * error reporting class used by this library. + * @see #google::cloud::StatusOr for a description of the error reporting class + * used by this library. * * @see `LimitedTimeRetryPolicy` and `LimitedErrorCountRetryPolicy` for * alternative retry policies. diff --git a/google/cloud/bigtable/table.h b/google/cloud/bigtable/table.h index d0b2e14b2fdf4..a6259baa11d2a 100644 --- a/google/cloud/bigtable/table.h +++ b/google/cloud/bigtable/table.h @@ -100,10 +100,8 @@ inline std::string TableName(std::shared_ptr const& client, * the `ok()` member function in the `StatusOr` returns `true` then it * contains the expected result. Operations that do not return a value simply * return a `google::cloud::Status` indicating success or the details of the - * error Please consult the - * [`StatusOr` - * documentation](#google::cloud::omit_this_inline_ns::StatusOr) for more - * details. + * error Please consult the [`StatusOr` + * documentation](#google::cloud::StatusOr) for more details. * * @code * namespace cbt = google::cloud::bigtable; @@ -154,8 +152,8 @@ inline std::string TableName(std::shared_ptr const& client, * @see https://cloud.google.com/bigtable/docs/reference/service-apis-overview * for an overview of the underlying Cloud Bigtable API. * - * @see #google::cloud::omit_this_inline_ns::StatusOr for a description of the - * error reporting class used by this library. + * @see #google::cloud::StatusOr for a description of the error reporting class + * used by this library. * * @see `LimitedTimeRetryPolicy` and `LimitedErrorCountRetryPolicy` for * alternative retry policies. diff --git a/google/cloud/bigtable/table_admin.h b/google/cloud/bigtable/table_admin.h index 5e5afcd4a4140..5f02e715c868f 100644 --- a/google/cloud/bigtable/table_admin.h +++ b/google/cloud/bigtable/table_admin.h @@ -71,10 +71,8 @@ enum class Consistency { * the `ok()` member function in the `StatusOr` returns `true` then it * contains the expected result. Operations that do not return a value simply * return a `google::cloud::Status` indicating success or the details of the - * error Please consult the - * [`StatusOr` - * documentation](#google::cloud::omit_this_inline_ns::StatusOr) for more - * details. + * error Please consult the [`StatusOr` + * documentation](#google::cloud::StatusOr) for more details. * * @code * namespace cbt = google::cloud::bigtable; @@ -122,8 +120,8 @@ enum class Consistency { * @see https://cloud.google.com/bigtable/docs/reference/service-apis-overview * for an overview of the underlying Cloud Bigtable API. * - * @see #google::cloud::omit_this_inline_ns::StatusOr for a description of the - * error reporting class used by this library. + * @see #google::cloud::StatusOr for a description of the error reporting class + * used by this library. * * @see `LimitedTimeRetryPolicy` and `LimitedErrorCountRetryPolicy` for * alternative retry policies. diff --git a/google/cloud/doc/common-main.dox b/google/cloud/doc/common-main.dox index 8f36402f8bbbf..74c3fc128a81b 100644 --- a/google/cloud/doc/common-main.dox +++ b/google/cloud/doc/common-main.dox @@ -6,16 +6,15 @@ This library contains common components shared by all the Google Cloud C++ Client Libraries. Including: -- [Status](@ref google::cloud::omit_this_inline_ns::Status) error codes and details from an +- [Status](@ref google::cloud::Status) error codes and details from an operation. -- [StatusOr](@ref google::cloud::omit_this_inline_ns::StatusOr) returns a value on success +- [StatusOr](@ref google::cloud::StatusOr) returns a value on success and a `Status` on error. -- [future](@ref google::cloud::omit_this_inline_ns::future) and - [promise](@ref google::cloud::omit_this_inline_ns::promise) futures (a holder that will - receive a value asynchronously) and promises (the counterpart of a future, - where values are stored asynchronously). They satisfy the API for - `std::future` and `std::promise`, and add support for callbacks and - cancellation. +- [future](@ref google::cloud::future) and + [promise](@ref google::cloud::promise) futures (a holder that will receive + a value asynchronously) and promises (the counterpart of a future, where + values are stored asynchronously). They satisfy the API for `std::future` and + `std::promise`, and add support for callbacks and cancellation. @warning The symbols in the `google::cloud::internal` namespace are implementation details and subject to change and/or removal without notice. diff --git a/google/cloud/pubsub/mocks/mock_ack_handler.h b/google/cloud/pubsub/mocks/mock_ack_handler.h index f43a913fd3f88..b760d7c70af35 100644 --- a/google/cloud/pubsub/mocks/mock_ack_handler.h +++ b/google/cloud/pubsub/mocks/mock_ack_handler.h @@ -37,8 +37,7 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN /** * A googlemock-based mock for [pubsub::AckHandler::Impl][mocked-link] * - * [mocked-link]: @ref - * google::cloud::pubsub::omit_this_inline_ns::AckHandler::Impl + * [mocked-link]: @ref google::cloud::pubsub::AckHandler::Impl * * @see @ref subscriber-mock for an example using this class. */ diff --git a/google/cloud/pubsub/mocks/mock_publisher_connection.h b/google/cloud/pubsub/mocks/mock_publisher_connection.h index 95ba342ab7e16..44cc9705d1ca8 100644 --- a/google/cloud/pubsub/mocks/mock_publisher_connection.h +++ b/google/cloud/pubsub/mocks/mock_publisher_connection.h @@ -27,8 +27,7 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN /** * A googlemock-based mock for [pubsub::PublisherConnection][mocked-link] * - * [mocked-link]: @ref - * google::cloud::pubsub::omit_this_inline_ns::PublisherConnection + * [mocked-link]: @ref google::cloud::pubsub::PublisherConnection * * @see @ref publisher-mock for an example using this class. */ diff --git a/google/cloud/pubsub/mocks/mock_schema_admin_connection.h b/google/cloud/pubsub/mocks/mock_schema_admin_connection.h index e99dc1d1e2aad..52368be40315d 100644 --- a/google/cloud/pubsub/mocks/mock_schema_admin_connection.h +++ b/google/cloud/pubsub/mocks/mock_schema_admin_connection.h @@ -27,8 +27,7 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN * A googlemock-based mock for * [pubsub::SchemaAdminConnection][mocked-link] * - * [mocked-link]: @ref - * google::cloud::pubsub::omit_this_inline_ns::SchemaAdminConnection + * [mocked-link]: @ref google::cloud::pubsub::SchemaAdminConnection */ class MockSchemaAdminConnection : public pubsub::SchemaAdminConnection { public: diff --git a/google/cloud/pubsub/mocks/mock_subscriber_connection.h b/google/cloud/pubsub/mocks/mock_subscriber_connection.h index 0b530999f0f46..9e8b8ff20ee95 100644 --- a/google/cloud/pubsub/mocks/mock_subscriber_connection.h +++ b/google/cloud/pubsub/mocks/mock_subscriber_connection.h @@ -26,8 +26,7 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN /** * A googlemock-based mock for [pubsub::SubscriberConnection][mocked-link] * - * [mocked-link]: @ref - * google::cloud::pubsub::omit_this_inline_ns::SubscriberConnection + * [mocked-link]: @ref google::cloud::pubsub::SubscriberConnection * * @see @ref subscriber-mock for an example using this class. */ diff --git a/google/cloud/pubsub/mocks/mock_subscription_admin_connection.h b/google/cloud/pubsub/mocks/mock_subscription_admin_connection.h index 47d44d3040111..7bdbb834da212 100644 --- a/google/cloud/pubsub/mocks/mock_subscription_admin_connection.h +++ b/google/cloud/pubsub/mocks/mock_subscription_admin_connection.h @@ -27,8 +27,7 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN * A googlemock-based mock for * [pubsub::SubscriptionAdminConnection][mocked-link] * - * [mocked-link]: @ref - * google::cloud::pubsub::omit_this_inline_ns::SubscriptionAdminConnection + * [mocked-link]: @ref google::cloud::pubsub::SubscriptionAdminConnection */ class MockSubscriptionAdminConnection : public pubsub::SubscriptionAdminConnection { diff --git a/google/cloud/pubsub/mocks/mock_topic_admin_connection.h b/google/cloud/pubsub/mocks/mock_topic_admin_connection.h index bfb2b192170e5..51ce95f185b9d 100644 --- a/google/cloud/pubsub/mocks/mock_topic_admin_connection.h +++ b/google/cloud/pubsub/mocks/mock_topic_admin_connection.h @@ -26,8 +26,7 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN /** * A googlemock-based mock for [pubsub::TopicAdminConnection][mocked-link] * - * [mocked-link]: @ref - * google::cloud::pubsub::omit_this_inline_ns::TopicAdminConnection + * [mocked-link]: @ref google::cloud::pubsub::TopicAdminConnection */ class MockTopicAdminConnection : public pubsub::TopicAdminConnection { public: diff --git a/google/cloud/pubsub/publisher.h b/google/cloud/pubsub/publisher.h index 50488c0cb62f6..60d59f022dff7 100644 --- a/google/cloud/pubsub/publisher.h +++ b/google/cloud/pubsub/publisher.h @@ -67,10 +67,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN * @par Background Threads * This class uses the background threads configured via the `Options` from * `GrpcOptionList`. Applications can create their own pool of background - * threads by (a) creating their own - * #google::cloud::omit_this_inline_ns::CompletionQueue, (b) passing this - * completion queue as a `GrpcCompletionQueueOption`, and (c) attaching any - * number of threads to the completion queue. + * threads by (a) creating their own #google::cloud::CompletionQueue, (b) + * passing this completion queue as a `GrpcCompletionQueueOption`, and (c) + * attaching any number of threads to the completion queue. * * @par Example: using a custom thread pool * @snippet samples.cc custom-thread-pool-publisher @@ -81,16 +80,15 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN * [`std::future`][std-future-link]. Our version adds a `.then()` function to * attach a callback to the future, which is invoked when the future is * satisfied. This function returns a `future` where `U` is the return value - * of the attached function. More details in the - * #google::cloud::omit_this_inline_ns::future documentation. + * of the attached function. More details in the #google::cloud::future + * documentation. * * @par Error Handling * This class uses `StatusOr` to report errors. When an operation fails to * perform its work the returned `StatusOr` contains the error details. If * the `ok()` member function in the `StatusOr` returns `true` then it - * contains the expected result. Please consult the - * #google::cloud::omit_this_inline_ns::StatusOr documentation for more - * details. + * contains the expected result. Please consult the #google::cloud::StatusOr + * documentation for more details. * * @par Batching Configuration Example * @snippet samples.cc publisher-options diff --git a/google/cloud/pubsub/schema_admin_client.h b/google/cloud/pubsub/schema_admin_client.h index 87b9d3f57a146..6ce3dd67d775f 100644 --- a/google/cloud/pubsub/schema_admin_client.h +++ b/google/cloud/pubsub/schema_admin_client.h @@ -54,10 +54,8 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN * This class uses `StatusOr` to report errors. When an operation fails to * perform its work the returned `StatusOr` contains the error details. If * the `ok()` member function in the `StatusOr` returns `true` then it - * contains the expected result. Please consult the - * [`StatusOr` - * documentation](#google::cloud::omit_this_inline_ns::StatusOr) for more - * details. + * contains the expected result. Please consult the [`StatusOr` + * documentation](#google::cloud::StatusOr) for more details. * * [pubsub-doc-link]: https://cloud.google.com/pubsub/docs */ diff --git a/google/cloud/pubsub/subscriber.h b/google/cloud/pubsub/subscriber.h index 1571029bf71fc..5d42ea16a28d2 100644 --- a/google/cloud/pubsub/subscriber.h +++ b/google/cloud/pubsub/subscriber.h @@ -58,10 +58,9 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN * @par Background Threads * This class uses the background threads configured via the `Options` from * `GrpcOptionList`. Applications can create their own pool of background - * threads by (a) creating their own - * #google::cloud::omit_this_inline_ns::CompletionQueue, (b) passing this - * completion queue as a `GrpcCompletionQueueOption`, and (c) attaching any - * number of threads to the completion queue. + * threads by (a) creating their own #google::cloud::CompletionQueue, (b) + * passing this completion queue as a `GrpcCompletionQueueOption`, and (c) + * attaching any number of threads to the completion queue. * * @par Example: using a custom thread pool * @snippet samples.cc custom-thread-pool-subscriber @@ -72,16 +71,15 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN * [`std::future`][std-future-link]. Our version adds a `.then()` function to * attach a callback to the future, which is invoked when the future is * satisfied. This function returns a `future` where `U` is the return value - * of the attached function. More details in the - * #google::cloud::omit_this_inline_ns::future documentation. + * of the attached function. More details in the #google::cloud::future + * documentation. * * @par Error Handling * This class uses `StatusOr` to report errors. When an operation fails to * perform its work the returned `StatusOr` contains the error details. If * the `ok()` member function in the `StatusOr` returns `true` then it - * contains the expected result. Please consult the - * #google::cloud::omit_this_inline_ns::StatusOr documentation for more - * details. + * contains the expected result. Please consult the #google::cloud::StatusOr + * documentation for more details. * * @par Changing Retry Parameters Example * @snippet samples.cc subscriber-retry-settings diff --git a/google/cloud/pubsub/subscription_admin_client.h b/google/cloud/pubsub/subscription_admin_client.h index e76ce0e57524a..73793eea5faea 100644 --- a/google/cloud/pubsub/subscription_admin_client.h +++ b/google/cloud/pubsub/subscription_admin_client.h @@ -52,10 +52,8 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN * This class uses `StatusOr` to report errors. When an operation fails to * perform its work the returned `StatusOr` contains the error details. If * the `ok()` member function in the `StatusOr` returns `true` then it - * contains the expected result. Please consult the - * [`StatusOr` - * documentation](#google::cloud::omit_this_inline_ns::StatusOr) for more - * details. + * contains the expected result. Please consult the [`StatusOr` + * documentation](#google::cloud::StatusOr) for more details. * * [pubsub-doc-link]: https://cloud.google.com/pubsub/docs */ diff --git a/google/cloud/pubsub/topic_admin_client.h b/google/cloud/pubsub/topic_admin_client.h index ec970e1233d74..f8b222e374acb 100644 --- a/google/cloud/pubsub/topic_admin_client.h +++ b/google/cloud/pubsub/topic_admin_client.h @@ -51,10 +51,8 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN * This class uses `StatusOr` to report errors. When an operation fails to * perform its work the returned `StatusOr` contains the error details. If * the `ok()` member function in the `StatusOr` returns `true` then it - * contains the expected result. Please consult the - * [`StatusOr` - * documentation](#google::cloud::omit_this_inline_ns::StatusOr) for more - * details. + * contains the expected result. Please consult the [`StatusOr` + * documentation](#google::cloud::StatusOr) for more details. * * [pubsub-doc-link]: https://cloud.google.com/pubsub/docs */ diff --git a/google/cloud/spanner/doc/spanner-main.dox b/google/cloud/spanner/doc/spanner-main.dox index da573d99fd49b..2da8a4e26c7d5 100644 --- a/google/cloud/spanner/doc/spanner-main.dox +++ b/google/cloud/spanner/doc/spanner-main.dox @@ -137,8 +137,8 @@ there is no value. The library automatically retries requests that fail with transient errors, and follows the recommended practices with respect to backoff between retries. Application developers can override the default -[retry](@ref google::cloud::spanner::omit_this_inline_ns::RetryPolicy) and -[backoff](@ref google::cloud::spanner::omit_this_inline_ns::BackoffPolicy) policies. +[retry](@ref google::cloud::spanner::RetryPolicy) and +[backoff](@ref google::cloud::spanner::BackoffPolicy) policies. The default policies are to continue retrying for up to 15 minutes, and to use truncated (at 5 minutes) exponential backoff, doubling the maximum backoff @@ -146,11 +146,11 @@ period between retries. @snippet samples.cc custom-retry-policy -@see [LimitedTimeRetryPolicy](@ref google::cloud::spanner::omit_this_inline_ns::LimitedTimeRetryPolicy) - and [LimitedErrorCountRetryPolicy](@ref google::cloud::spanner::omit_this_inline_ns::LimitedErrorCountRetryPolicy) +@see [LimitedTimeRetryPolicy](@ref google::cloud::spanner::LimitedTimeRetryPolicy) + and [LimitedErrorCountRetryPolicy](@ref google::cloud::spanner::LimitedErrorCountRetryPolicy) for alternative retry policies. -@see [ExponentialBackoffPolicy](@ref google::cloud::spanner::omit_this_inline_ns::ExponentialBackoffPolicy) +@see [ExponentialBackoffPolicy](@ref google::cloud::spanner::ExponentialBackoffPolicy) to configure different parameters for the exponential backoff policy. ## Next Steps diff --git a/google/cloud/storage/client.h b/google/cloud/storage/client.h index 1d73d76950f4c..c6c2d2555493a 100644 --- a/google/cloud/storage/client.h +++ b/google/cloud/storage/client.h @@ -109,10 +109,8 @@ struct ClientImplDetails; * This class uses `StatusOr` to report errors. When an operation fails to * perform its work the returned `StatusOr` contains the error details. If * the `ok()` member function in the `StatusOr` returns `true` then it - * contains the expected result. Please consult the - * [`StatusOr` - * documentation](#google::cloud::omit_this_inline_ns::StatusOr) for more - * details. + * contains the expected result. Please consult the [`StatusOr` + * documentation](#google::cloud::StatusOr) for more details. * * @code * namespace gcs = google::cloud::storage; @@ -183,7 +181,7 @@ struct ClientImplDetails; * @see https://cloud.google.com/docs/authentication/production for details * about Application Default %Credentials. * - * @see #google::cloud::omit_this_inline_ns::StatusOr. + * @see #google::cloud::StatusOr. * * @see `LimitedTimeRetryPolicy` and `LimitedErrorCountRetryPolicy` for * alternative retry policies. @@ -624,8 +622,7 @@ class Client { } /** - * Fetches the [IAM policy](@ref - * google::cloud::omit_this_inline_ns::IamPolicy) for a Bucket. + * Fetches the [IAM policy](@ref google::cloud::IamPolicy) for a Bucket. * * Google Cloud Identity & Access Management (IAM) lets administrators * authorize who can take action on specific resources, including Google @@ -657,8 +654,7 @@ class Client { * @par Example * Use #GetNativeBucketIamPolicy() instead. * - * @see #google::cloud::omit_this_inline_ns::IamPolicy for details about the - * `IamPolicy` class. + * @see #google::cloud::IamPolicy for details about the `IamPolicy` class. */ template GOOGLE_CLOUD_CPP_STORAGE_IAM_DEPRECATED("GetNativeBucketIamPolicy") @@ -670,8 +666,8 @@ class Client { } /** - * Fetches the native [IAM policy](@ref - * google::cloud::omit_this_inline_ns::IamPolicy) for a Bucket. + * Fetches the native [IAM policy](@ref google::cloud::IamPolicy) for a + * Bucket. * * Google Cloud Identity & Access Management (IAM) lets administrators * authorize who can take action on specific resources, including Google @@ -699,8 +695,7 @@ class Client { * @par Example * @snippet storage_bucket_iam_samples.cc native get bucket iam policy * - * @see #google::cloud::omit_this_inline_ns::IamPolicy for details about the - * `IamPolicy` class. + * @see #google::cloud::IamPolicy for details about the `IamPolicy` class. */ template StatusOr GetNativeBucketIamPolicy( @@ -711,8 +706,7 @@ class Client { } /** - * Sets the [IAM Policy](@ref google::cloud::omit_this_inline_ns::IamPolicy) - * for a Bucket. + * Sets the [IAM Policy](@ref google::cloud::IamPolicy) for a Bucket. * * Google Cloud Identity & Access Management (IAM) lets administrators * authorize who can take action on specific resources, including Google @@ -754,8 +748,7 @@ class Client { * @par Example: adding a new member * Use #GetNativeBucketIamPolicy() instead. * - * @see #google::cloud::omit_this_inline_ns::IamPolicy for details about the - * `IamPolicy` class. + * @see #google::cloud::IamPolicy for details about the `IamPolicy` class. */ template GOOGLE_CLOUD_CPP_STORAGE_IAM_DEPRECATED("SetNativeBucketIamPolicy") @@ -768,8 +761,7 @@ class Client { } /** - * Sets the native [IAM Policy](@ref - * google::cloud::omit_this_inline_ns::IamPolicy) for a Bucket. + * Sets the native [IAM Policy](@ref google::cloud::IamPolicy) for a Bucket. * * Google Cloud Identity & Access Management (IAM) lets administrators * authorize who can take action on specific resources, including Google @@ -810,8 +802,7 @@ class Client { * @par Example: removing a IAM member * @snippet storage_bucket_iam_samples.cc native remove bucket iam member * - * @see #google::cloud::omit_this_inline_ns::IamPolicy for details about the - * `IamPolicy` class. + * @see #google::cloud::IamPolicy for details about the `IamPolicy` class. */ template StatusOr SetNativeBucketIamPolicy( diff --git a/google/cloud/storage/doc/storage-main.dox b/google/cloud/storage/doc/storage-main.dox index 923d8ee717e8e..f046cd89d0570 100644 --- a/google/cloud/storage/doc/storage-main.dox +++ b/google/cloud/storage/doc/storage-main.dox @@ -149,11 +149,11 @@ using gcs = ::google::cloud::storage; ### Retry, Backoff, and Idempotency Policies. The library automatically retries requests that fail with transient errors, and -follows the -[recommended practice](https://cloud.google.com/storage/docs/exponential-backoff) -to backoff between retries. Application developers can override the default -[retry](@ref google::cloud::storage::omit_this_inline_ns::RetryPolicy) and -[backoff](@ref google::cloud::storage::omit_this_inline_ns::BackoffPolicy) policies: +follows the [recommended +practice](https://cloud.google.com/storage/docs/exponential-backoff) to backoff +between retries. Application developers can override the default +[retry](@ref google::cloud::storage::RetryPolicy) and +[backoff](@ref google::cloud::storage::BackoffPolicy) policies: @snippet storage_object_samples.cc insert object modified retry @@ -163,20 +163,20 @@ period between retries. By default the library retries all operations, even those that are not idempotent. Application developers can override the -[idempotency policy](@ref google::cloud::storage::omit_this_inline_ns::Client::Client) -to follow a more conservative approach: +[idempotency policy](@ref google::cloud::storage::Client::Client) to follow a +more conservative approach: @snippet storage_object_samples.cc insert object strict idempotency -@see [LimitedTimeRetryPolicy](@ref google::cloud::storage::omit_this_inline_ns::LimitedTimeRetryPolicy) - and [LimitedErrorCountRetryPolicy](@ref google::cloud::storage::omit_this_inline_ns::LimitedErrorCountRetryPolicy) +@see [LimitedTimeRetryPolicy](@ref google::cloud::storage::LimitedTimeRetryPolicy) + and [LimitedErrorCountRetryPolicy](@ref google::cloud::storage::LimitedErrorCountRetryPolicy) for alternative retry policies. -@see [ExponentialBackoffPolicy](@ref google::cloud::storage::omit_this_inline_ns::ExponentialBackoffPolicy) +@see [ExponentialBackoffPolicy](@ref google::cloud::storage::ExponentialBackoffPolicy) to configure different parameters for the exponential backoff policy. -@see [AlwaysRetryIdempotencyPolicy](@ref google::cloud::storage::omit_this_inline_ns::AlwaysRetryIdempotencyPolicy) - and [StrictIdempotencyPolicy](@ref google::cloud::storage::omit_this_inline_ns::StrictIdempotencyPolicy) +@see [AlwaysRetryIdempotencyPolicy](@ref google::cloud::storage::AlwaysRetryIdempotencyPolicy) + and [StrictIdempotencyPolicy](@ref google::cloud::storage::StrictIdempotencyPolicy) for alternative idempotency policies. ### Next Steps @@ -192,11 +192,11 @@ good places to continue learning about the library. -[Client]: @ref google::cloud::storage::omit_this_inline_ns::Client -[ReadObject]: @ref google::cloud::storage::omit_this_inline_ns::Client::ReadObject() -[WriteObject]: @ref google::cloud::storage::omit_this_inline_ns::Client::WriteObject() -[ListObjects]: @ref google::cloud::storage::omit_this_inline_ns::Client::ListObjects() -[DeleteObject]: @ref google::cloud::storage::omit_this_inline_ns::Client::DeleteObject() +[Client]: @ref google::cloud::storage::Client +[ReadObject]: @ref google::cloud::storage::Client::ReadObject() +[WriteObject]: @ref google::cloud::storage::Client::WriteObject() +[ListObjects]: @ref google::cloud::storage::Client::ListObjects() +[DeleteObject]: @ref google::cloud::storage::Client::DeleteObject() [gcs-quickstart]: https://cloud.google.com/storage/docs/quickstarts 'GCS Quickstarts' diff --git a/google/cloud/storage/doc/storage-mocking.dox b/google/cloud/storage/doc/storage-mocking.dox index eaa2c1158a4ea..a7d5eb55e3b32 100644 --- a/google/cloud/storage/doc/storage-mocking.dox +++ b/google/cloud/storage/doc/storage-mocking.dox @@ -41,10 +41,10 @@ snippets on how to call the function. The snippets for [ListObjects()][ListObjects], and [DeleteObject()][DeleteObject] are good places to continue learning about the library. -[Client]: @ref google::cloud::storage::omit_this_inline_ns::Client -[ReadObject]: @ref google::cloud::storage::omit_this_inline_ns::Client::ReadObject() -[WriteObject]: @ref google::cloud::storage::omit_this_inline_ns::Client::WriteObject() -[ListObjects]: @ref google::cloud::storage::omit_this_inline_ns::Client::ListObjects() -[DeleteObject]: @ref google::cloud::storage::omit_this_inline_ns::Client::DeleteObject() +[Client]: @ref google::cloud::storage::Client +[ReadObject]: @ref google::cloud::storage::Client::ReadObject() +[WriteObject]: @ref google::cloud::storage::Client::WriteObject() +[ListObjects]: @ref google::cloud::storage::Client::ListObjects() +[DeleteObject]: @ref google::cloud::storage::Client::DeleteObject() */ From 12d90fe944dec5cbc03f46e287fb2de62cad5fdc Mon Sep 17 00:00:00 2001 From: Greg Miller <9447643+devjgm@users.noreply.github.com> Date: Thu, 14 Oct 2021 08:19:25 -0400 Subject: [PATCH 2/2] updated changelog advice --- CHANGELOG.md | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 153dcaac5fb29..3eca186968723 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -69,19 +69,13 @@ ## v1.33.0 - TBD -**ATTENTION**: Users should generally **NOT** spell the name of our versioned -inline namespace in their code, as doing so will tightly couple your code to a -specific version of our library and will make upgrades more difficult for you. -Previously, this version was `v1` (but it will change in the future), and so -you may have some code that references, say, ~`google::cloud::v1::Status`~ -(WRONG) and you should instead prefer `google::cloud::Status` (omit the -versioned inline namespace name). - -Our Doxygen documentation (e.g. [Storage docs][storage-dox-link]) was -incorrectly showing the versioned inline namespace name for our symbols, -implicitly suggesting that users should spell this inline namespace in their -own code. This mistake was fixed and our Doxygen documentation no longer shows -the versioned inline namespace name. +**ATTENTION**: Our Doxygen documentation (e.g. [Storage +docs][storage-dox-link]) was incorrectly showing the versioned inline namespace +name for our symbols (it was `v1`), implicitly suggesting that users should +spell this inline namespace in their own code. This mistake was fixed and our +Doxygen documentation no longer shows the versioned inline namespace name, now +showing users how to correctly spell our symbol names without referencing the +versioned inline namespace. [storage-dox-link]: https://googleapis.dev/cpp/google-cloud-storage/latest/