chore: add migration information to service class descriptions (#638)

src/Generation/GapicClientGenerator.php

@@ -42,6 +42,7 @@
 use Google\Generator\Collections\Map;
 use Google\Generator\Collections\Vector;
 use Google\Generator\Utils\Helpers;
+use Google\Generator\Utils\MigrationMode;
 use Google\Generator\Utils\ResolvedType;
 use Google\Generator\Utils\Transport;
 use Google\Generator\Utils\Type;
@@ -119,6 +120,12 @@ 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->emptyClientV2Type->getFullname() . '} to use the new surface.'
+                    ) : null,
                 $this->serviceDetails->isGa() ? null : PhpDoc::experimental(),
                 !$this->serviceDetails->isDeprecated ? null : PhpDoc::deprecated(ServiceDetails::DEPRECATED_MSG)
             ))

src/Generation/GapicClientV2Generator.php

@@ -129,7 +129,16 @@ private function generateClass(): PhpClass
                     ),
                 // 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.'),
+                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(),
                 PhpDoc::internal(),
                 !$this->serviceDetails->isDeprecated ? null : PhpDoc::deprecated(ServiceDetails::DEPRECATED_MSG),

tests/Integration/goldens/redis/src/V1/Client/BaseClient/CloudRedisBaseClient.php

@@ -73,7 +73,8 @@
  * 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.
+ * This class is currently experimental and may be subject to changes. See {@see
+ * \Google\Cloud\Redis\V1\CloudRedisClient} for the stable implementation
  *
  * @experimental
  *

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

@@ -112,6 +112,9 @@
  * 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.
+ *
+ * This service has a new (beta) implementation. See {@see
+ * \Google\Cloud\Redis\V1\Client\CloudRedisClient} to use the new surface.
  */
 class CloudRedisGapicClient
 {

tests/Integration/goldens/securitycenter/src/V1/Client/BaseClient/SecurityCenterBaseClient.php

@@ -79,7 +79,9 @@
  * 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.
+ * This class is currently experimental and may be subject to changes. See {@see
+ * \Google\Cloud\SecurityCenter\V1\SecurityCenterClient} for the stable
+ * implementation
  *
  * @experimental
  *

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

@@ -101,6 +101,10 @@
  * 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.
+ *
+ * This service has a new (beta) implementation. See {@see
+ * \Google\Cloud\SecurityCenter\V1\Client\SecurityCenterClient} to use the new
+ * surface.
  */
 class SecurityCenterGapicClient
 {

tests/Unit/ProtoTests/ResourceNames/out/src/Client/BaseClient/ResourceNamesBaseClient.php

@@ -55,7 +55,8 @@
  * 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.
+ * This class is currently experimental and may be subject to changes. See {@see
+ * \Testing\ResourceNames\ResourceNamesClient} for the stable implementation
  *
  * @experimental
  *

tests/Unit/ProtoTests/ResourceNames/out/src/Gapic/ResourceNamesGapicClient.php

@@ -69,6 +69,9 @@
  * 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.
+ *
+ * This service has a new (beta) implementation. See {@see
+ * \Testing\ResourceNames\Client\ResourceNamesClient} to use the new surface.
  */
 class ResourceNamesGapicClient
 {

tests/Unit/ProtoTests/RoutingHeaders/out/src/Client/BaseClient/RoutingHeadersBaseClient.php

@@ -43,7 +43,8 @@
  * 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.
+ * This class is currently experimental and may be subject to changes. See {@see
+ * \Testing\RoutingHeaders\RoutingHeadersClient} for the stable implementation
  *
  * @experimental
  *

tests/Unit/ProtoTests/RoutingHeaders/out/src/Gapic/RoutingHeadersGapicClient.php

@@ -52,6 +52,9 @@
  *     $routingHeadersClient->close();
  * }
  * ```
+ *
+ * This service has a new (beta) implementation. See {@see
+ * \Testing\RoutingHeaders\Client\RoutingHeadersClient} to use the new surface.
  */
 class RoutingHeadersGapicClient
 {