feat: mark new surface GA and previous surface deprecated (#674)

src/Generation/GapicClientGenerator.php

@@ -120,14 +120,13 @@ private function generateClass(): PhpClass
                         'a parseName method to extract the individual identifiers contained within formatted names ' .
                         'that are returned by the API.'
                      ),
-                // If this service contains both client surfaces, link to the new surface.
-                in_array($this->serviceDetails->migrationMode, [MigrationMode::MIGRATING, MigrationMode::MIGRATION_MODE_UNSPECIFIED])
-                    ? PhpDoc::text(
-                        'This service has a new (beta) implementation. See {@see ' .
-                        $this->serviceDetails->gapicClientV2Type->getFullname() . '} to use the new surface.'
-                    ) : null,
                 $this->serviceDetails->isGa() ? null : PhpDoc::experimental(),
-                !$this->serviceDetails->isDeprecated ? null : PhpDoc::deprecated(ServiceDetails::DEPRECATED_MSG)
+                PhpDoc::deprecated(
+                    // If this service contains both client surfaces, link to the new surface.
+                    in_array($this->serviceDetails->migrationMode, [MigrationMode::MIGRATING, MigrationMode::MIGRATION_MODE_UNSPECIFIED])
+                        ? 'Please use the new service client {@see ' . $this->serviceDetails->gapicClientV2Type->getFullname() . '}.'
+                        : ServiceDetails::DEPRECATED_MSG
+                )
             ))
             ->withTrait($this->ctx->type(Type::fromName(\Google\ApiCore\GapicClientTrait::class)))
             ->withMember($this->serviceName())

src/Generation/GapicClientV2Generator.php

@@ -127,19 +127,7 @@ private function generateClass(): PhpClass
                         'a parseName method to extract the individual identifiers contained within formatted names ' .
                         'that are returned by the API.'
                     ),
-                // TODO(#594): Uncomment this and remove the following two lines when stable.
-                // $this->serviceDetails->isGa() ? null : PhpDoc::experimental(),
-                PhpDoc::text(
-                    'This class is currently experimental and may be subject to changes.' .
-                    // If this service is GA and contains both client surfaces, link to the stable surface.
-                    ($this->serviceDetails->isGa() && in_array(
-                        $this->serviceDetails->migrationMode,
-                        [MigrationMode::MIGRATING, MigrationMode::MIGRATION_MODE_UNSPECIFIED]
-                    )
-                        ? ' See {@see ' . $this->serviceDetails->emptyClientType->getFullname() . '} for the stable implementation'
-                        : '')
-                ),
-                PhpDoc::experimental(),
+                $this->serviceDetails->isGa() ? null : PhpDoc::experimental(),
                 !$this->serviceDetails->isDeprecated ? null : PhpDoc::deprecated(ServiceDetails::DEPRECATED_MSG),
                 $this->serviceDetails->streamingOnly ? null : $this->magicAsyncDocs(),
             ))

tests/Integration/goldens/asset/src/V1/Gapic/AssetServiceGapicClient.php

@@ -87,6 +87,8 @@
  * assist with these names, this class includes a format method for each type of
  * name, and additionally a parseName method to extract the individual identifiers
  * contained within formatted names that are returned by the API.
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class AssetServiceGapicClient
 {

tests/Integration/goldens/compute_small/src/V1/Gapic/AddressesGapicClient.php

@@ -73,6 +73,8 @@
  *     $addressesClient->close();
  * }
  * ```
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class AddressesGapicClient
 {

tests/Integration/goldens/compute_small/src/V1/Gapic/RegionOperationsGapicClient.php

@@ -52,6 +52,8 @@
  *     $regionOperationsClient->close();
  * }
  * ```
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class RegionOperationsGapicClient
 {

tests/Integration/goldens/container/src/V1/Gapic/ClusterManagerGapicClient.php

@@ -99,6 +99,8 @@
  *     $clusterManagerClient->close();
  * }
  * ```
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class ClusterManagerGapicClient
 {

tests/Integration/goldens/dataproc/src/V1/Gapic/AutoscalingPolicyServiceGapicClient.php

@@ -64,6 +64,8 @@
  * assist with these names, this class includes a format method for each type of
  * name, and additionally a parseName method to extract the individual identifiers
  * contained within formatted names that are returned by the API.
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class AutoscalingPolicyServiceGapicClient
 {

tests/Integration/goldens/dataproc/src/V1/Gapic/ClusterControllerGapicClient.php

@@ -99,6 +99,8 @@
  * assist with these names, this class includes a format method for each type of
  * name, and additionally a parseName method to extract the individual identifiers
  * contained within formatted names that are returned by the API.
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class ClusterControllerGapicClient
 {

tests/Integration/goldens/dataproc/src/V1/Gapic/JobControllerGapicClient.php

@@ -64,6 +64,8 @@
  *     $jobControllerClient->close();
  * }
  * ```
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class JobControllerGapicClient
 {

tests/Integration/goldens/dataproc/src/V1/Gapic/WorkflowTemplateServiceGapicClient.php

@@ -70,6 +70,8 @@
  * assist with these names, this class includes a format method for each type of
  * name, and additionally a parseName method to extract the individual identifiers
  * contained within formatted names that are returned by the API.
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class WorkflowTemplateServiceGapicClient
 {

tests/Integration/goldens/functions/src/V1/Client/CloudFunctionsServiceClient.php

@@ -66,10 +66,6 @@
  * name, and additionally a parseName method to extract the individual identifiers
  * contained within formatted names that are returned by the API.
  *
- * This class is currently experimental and may be subject to changes.
- *
- * @experimental
- *
  * @method PromiseInterface callFunctionAsync(CallFunctionRequest $request, array $optionalArgs = [])
  * @method PromiseInterface createFunctionAsync(CreateFunctionRequest $request, array $optionalArgs = [])
  * @method PromiseInterface deleteFunctionAsync(DeleteFunctionRequest $request, array $optionalArgs = [])

tests/Integration/goldens/iam/src/V1/Gapic/IAMPolicyGapicClient.php

@@ -78,6 +78,8 @@
  *     $iAMPolicyClient->close();
  * }
  * ```
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class IAMPolicyGapicClient
 {

tests/Integration/goldens/kms/src/V1/Gapic/KeyManagementServiceGapicClient.php

@@ -117,6 +117,8 @@
  * assist with these names, this class includes a format method for each type of
  * name, and additionally a parseName method to extract the individual identifiers
  * contained within formatted names that are returned by the API.
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class KeyManagementServiceGapicClient
 {

tests/Integration/goldens/logging/src/V2/Gapic/ConfigServiceV2GapicClient.php

@@ -90,6 +90,8 @@
  * assist with these names, this class includes a format method for each type of
  * name, and additionally a parseName method to extract the individual identifiers
  * contained within formatted names that are returned by the API.
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class ConfigServiceV2GapicClient
 {

tests/Integration/goldens/logging/src/V2/Gapic/LoggingServiceV2GapicClient.php

@@ -69,6 +69,8 @@
  * assist with these names, this class includes a format method for each type of
  * name, and additionally a parseName method to extract the individual identifiers
  * contained within formatted names that are returned by the API.
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class LoggingServiceV2GapicClient
 {

tests/Integration/goldens/logging/src/V2/Gapic/MetricsServiceV2GapicClient.php

@@ -63,6 +63,8 @@
  * assist with these names, this class includes a format method for each type of
  * name, and additionally a parseName method to extract the individual identifiers
  * contained within formatted names that are returned by the API.
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class MetricsServiceV2GapicClient
 {

tests/Integration/goldens/redis/src/V1/Client/CloudRedisClient.php

@@ -73,11 +73,6 @@
  * name, and additionally a parseName method to extract the individual identifiers
  * contained within formatted names that are returned by the API.
  *
- * This class is currently experimental and may be subject to changes. See {@see
- * \Google\Cloud\Redis\V1\CloudRedisClient} for the stable implementation
- *
- * @experimental
- *
  * @method PromiseInterface createInstanceAsync(CreateInstanceRequest $request, array $optionalArgs = [])
  * @method PromiseInterface deleteInstanceAsync(DeleteInstanceRequest $request, array $optionalArgs = [])
  * @method PromiseInterface exportInstanceAsync(ExportInstanceRequest $request, array $optionalArgs = [])

tests/Integration/goldens/redis/src/V1/Gapic/CloudRedisGapicClient.php

@@ -113,8 +113,7 @@
  * name, and additionally a parseName method to extract the individual identifiers
  * contained within formatted names that are returned by the API.
  *
- * This service has a new (beta) implementation. See {@see
- * \Google\Cloud\Redis\V1\Client\CloudRedisClient} to use the new surface.
+ * @deprecated Please use the new service client {@see \Google\Cloud\Redis\V1\Client\CloudRedisClient}.
  */
 class CloudRedisGapicClient
 {

tests/Integration/goldens/retail/src/V2alpha/Gapic/CatalogServiceGapicClient.php

@@ -66,6 +66,8 @@
  * contained within formatted names that are returned by the API.
  *
  * @experimental
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class CatalogServiceGapicClient
 {

tests/Integration/goldens/retail/src/V2alpha/Gapic/CompletionServiceGapicClient.php

@@ -70,6 +70,8 @@
  * contained within formatted names that are returned by the API.
  *
  * @experimental
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class CompletionServiceGapicClient
 {

tests/Integration/goldens/retail/src/V2alpha/Gapic/PredictionServiceGapicClient.php

@@ -62,6 +62,8 @@
  * contained within formatted names that are returned by the API.
  *
  * @experimental
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class PredictionServiceGapicClient
 {

tests/Integration/goldens/retail/src/V2alpha/Gapic/ProductServiceGapicClient.php

@@ -107,6 +107,8 @@
  * contained within formatted names that are returned by the API.
  *
  * @experimental
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class ProductServiceGapicClient
 {

tests/Integration/goldens/retail/src/V2alpha/Gapic/SearchServiceGapicClient.php

@@ -83,6 +83,8 @@
  * contained within formatted names that are returned by the API.
  *
  * @experimental
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class SearchServiceGapicClient
 {

tests/Integration/goldens/retail/src/V2alpha/Gapic/UserEventServiceGapicClient.php

@@ -72,6 +72,8 @@
  * contained within formatted names that are returned by the API.
  *
  * @experimental
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class UserEventServiceGapicClient
 {

tests/Integration/goldens/securitycenter/src/V1/Client/SecurityCenterClient.php

@@ -79,12 +79,6 @@
  * name, and additionally a parseName method to extract the individual identifiers
  * contained within formatted names that are returned by the API.
  *
- * This class is currently experimental and may be subject to changes. See {@see
- * \Google\Cloud\SecurityCenter\V1\SecurityCenterClient} for the stable
- * implementation
- *
- * @experimental
- *
  * @method PromiseInterface createFindingAsync(CreateFindingRequest $request, array $optionalArgs = [])
  * @method PromiseInterface createNotificationConfigAsync(CreateNotificationConfigRequest $request, array $optionalArgs = [])
  * @method PromiseInterface createSourceAsync(CreateSourceRequest $request, array $optionalArgs = [])

tests/Integration/goldens/securitycenter/src/V1/Gapic/SecurityCenterGapicClient.php

@@ -102,9 +102,7 @@
  * name, and additionally a parseName method to extract the individual identifiers
  * contained within formatted names that are returned by the API.
  *
- * This service has a new (beta) implementation. See {@see
- * \Google\Cloud\SecurityCenter\V1\Client\SecurityCenterClient} to use the new
- * surface.
+ * @deprecated Please use the new service client {@see \Google\Cloud\SecurityCenter\V1\Client\SecurityCenterClient}.
  */
 class SecurityCenterGapicClient
 {

tests/Integration/goldens/speech/src/V1/Gapic/SpeechGapicClient.php

@@ -86,6 +86,8 @@
  *     $speechClient->close();
  * }
  * ```
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class SpeechGapicClient
 {

tests/Integration/goldens/talent/src/V4beta1/Gapic/ApplicationServiceGapicClient.php

@@ -69,6 +69,8 @@
  * contained within formatted names that are returned by the API.
  *
  * @experimental
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class ApplicationServiceGapicClient
 {

tests/Integration/goldens/talent/src/V4beta1/Gapic/CompanyServiceGapicClient.php

@@ -68,6 +68,8 @@
  * contained within formatted names that are returned by the API.
  *
  * @experimental
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class CompanyServiceGapicClient
 {

tests/Integration/goldens/talent/src/V4beta1/Gapic/CompletionGapicClient.php

@@ -64,6 +64,8 @@
  * contained within formatted names that are returned by the API.
  *
  * @experimental
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class CompletionGapicClient
 {

tests/Integration/goldens/talent/src/V4beta1/Gapic/EventServiceGapicClient.php

@@ -61,6 +61,8 @@
  * contained within formatted names that are returned by the API.
  *
  * @experimental
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class EventServiceGapicClient
 {

tests/Integration/goldens/talent/src/V4beta1/Gapic/JobServiceGapicClient.php

@@ -109,6 +109,8 @@
  * contained within formatted names that are returned by the API.
  *
  * @experimental
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class JobServiceGapicClient
 {

tests/Integration/goldens/talent/src/V4beta1/Gapic/ProfileServiceGapicClient.php

@@ -74,6 +74,8 @@
  * contained within formatted names that are returned by the API.
  *
  * @experimental
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class ProfileServiceGapicClient
 {

tests/Integration/goldens/talent/src/V4beta1/Gapic/TenantServiceGapicClient.php

@@ -68,6 +68,8 @@
  * contained within formatted names that are returned by the API.
  *
  * @experimental
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class TenantServiceGapicClient
 {

tests/Integration/goldens/videointelligence/src/V1/Gapic/VideoIntelligenceServiceGapicClient.php

@@ -79,6 +79,8 @@
  *     $videoIntelligenceServiceClient->close();
  * }
  * ```
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class VideoIntelligenceServiceGapicClient
 {

tests/Tools/ConfigLoader.php

@@ -18,7 +18,7 @@
 
 namespace Google\Generator\Tests\Tools;
 
-trait ConfigLoader
+class ConfigLoader
 {
     /**
      * Load a config file from the specified path, which must be relative to the `tests/Unit` directory.

tests/Unit/ProtoTests/Basic/out/src/Client/BasicClient.php

@@ -42,10 +42,6 @@
  * This class provides the ability to make remote calls to the backing service through method
  * calls that map to API methods.
  *
- * This class is currently experimental and may be subject to changes.
- *
- * @experimental
- *
  * @method PromiseInterface aMethodAsync(Request $request, array $optionalArgs = [])
  * @method PromiseInterface methodWithArgsAsync(RequestWithArgs $request, array $optionalArgs = [])
  */

tests/Unit/ProtoTests/BasicBidiStreaming/out/src/Gapic/BasicBidiStreamingGapicClient.php

@@ -81,6 +81,8 @@
  *     $basicBidiStreamingClient->close();
  * }
  * ```
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class BasicBidiStreamingGapicClient
 {

tests/Unit/ProtoTests/BasicClientStreaming/out/src/Gapic/BasicClientStreamingGapicClient.php

@@ -69,6 +69,8 @@
  *     $basicClientStreamingClient->close();
  * }
  * ```
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class BasicClientStreamingGapicClient
 {

tests/Unit/ProtoTests/BasicDiregapic/out/src/Gapic/LibraryGapicClient.php

@@ -134,6 +134,8 @@
  * assist with these names, this class includes a format method for each type of
  * name, and additionally a parseName method to extract the individual identifiers
  * contained within formatted names that are returned by the API.
+ *
+ * @deprecated This class will be removed in the next major version update.
  */
 class LibraryGapicClient
 {