feat: support external links for Guzzle Promise Interface (#7778)

googleapis · Oct 30, 2024 · 3c82c64 · 3c82c64
1 parent ebac0c8
commit 3c82c64
Show file tree

Hide file tree

Showing 5 changed files with 100 additions and 50 deletions.
diff --git a/dev/src/DocFx/Node/XrefTrait.php b/dev/src/DocFx/Node/XrefTrait.php
@@ -159,34 +159,48 @@ private function replaceUidWithLink(string $uid, string $name = null): string
         // Remove preceeding "\" from namespace
         $name = $name ?: ltrim($uid, '\\');
 
+        // Case for generic types
+        if (preg_match('/(.*)<(.*)>/', $uid, $matches)) {
+            return sprintf(
+                '%s<%s>',
+                $this->replaceUidWithLink($matches[1]),
+                $this->replaceUidWithLink($matches[2])
+            );
+        }
+
         // Check for external package namespaces
         switch (true) {
-            case 0 === strpos($uid, '\Google\ApiCore\\'):
+            case str_starts_with($uid, '\Google\ApiCore\\'):
                 $extLinkRoot = 'https://googleapis.github.io/gax-php#';
                 break;
-            case 0 === strpos($uid, '\Google\Auth\\'):
+            case str_starts_with($uid, '\Google\Auth\\'):
                 $extLinkRoot = 'https://googleapis.github.io/google-auth-library-php/main/';
                 break;
-            case 0 === strpos($uid, '\Google\Protobuf\\'):
+            case str_starts_with($uid, '\Google\Protobuf\\'):
                 $extLinkRoot = 'https://protobuf.dev/reference/php/api-docs/';
                 break;
-            case 0 === strpos($uid, '\Google\Api\\'):
-            case 0 === strpos($uid, '\Google\Cloud\Iam\V1\\'):
-            case 0 === strpos($uid, '\Google\Cloud\Location\\'):
-            case 0 === strpos($uid, '\Google\Cloud\Logging\Type\\'):
-            case 0 === strpos($uid, '\Google\Iam\\'):
-            case 0 === strpos($uid, '\Google\Rpc\\'):
-            case 0 === strpos($uid, '\Google\Type\\'):
+            case str_starts_with($uid, '\Google\Api\\'):
+            case str_starts_with($uid, '\Google\Cloud\Iam\V1\\'):
+            case str_starts_with($uid, '\Google\Cloud\Location\\'):
+            case str_starts_with($uid, '\Google\Cloud\Logging\Type\\'):
+            case str_starts_with($uid, '\Google\Iam\\'):
+            case str_starts_with($uid, '\Google\Rpc\\'):
+            case str_starts_with($uid, '\Google\Type\\'):
                 $extLinkRoot = 'https://googleapis.github.io/common-protos-php#';
                 break;
+            case 0 === strpos($uid, '\GuzzleHttp\Promise\PromiseInterface'):
+                $extLinkRoot = 'https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html';
+                break;
             default:
                 $extLinkRoot = '';
         }
 
         // Create external link
         if ($extLinkRoot) {
-            $path = str_replace(['::', '\\', '()'], ['#method_', '/'], $name);
-            return sprintf('<a href="%s">%s</a>', $extLinkRoot . $path, $name);
+            if (str_starts_with($uid, '\Google')) {
+                $extLinkRoot .= str_replace(['::', '\\', '()'], ['#method_', '/'], $name);
+            }
+            return sprintf('<a href="%s">%s</a>', $extLinkRoot, $name);
         }
 
         return sprintf('<xref uid="%s">%s</xref>', $uid, $name);

diff --git a/dev/tests/Unit/DocFx/NodeTest.php b/dev/tests/Unit/DocFx/NodeTest.php
@@ -138,6 +138,42 @@ public function testSeeTagsInMethodDescription()
         );
     }
 
+    public function testReplaceGuzzleExternalLink()
+    {
+        $guzzlePromiseClassName = '\GuzzleHttp\Promise\PromiseInterface';
+        $expected = '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>';
+        $xref = new class {
+            use XrefTrait;
+
+            public function replace(string $uid) {
+                return $this->replaceUidWithLink($uid);
+            }
+        };
+
+        $result = $xref->replace($guzzlePromiseClassName);
+        $this->assertEquals($expected, $result);
+    }
+
+    public function testReplaceGenericPromiseClass()
+    {
+        $guzzlePromiseClassName = '\GuzzleHttp\Promise\PromiseInterface';
+        $googleReference = '\Google\Cloud\AdvisoryNotifications\V1\Notification';
+        $uid = $guzzlePromiseClassName . '<' . $googleReference . '>';
+
+        $expected = '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>';
+        $expected .= '<<xref uid="' . $googleReference . '">Google\Cloud\AdvisoryNotifications\V1\Notification</xref>>';
+        $xref = new class {
+            use XrefTrait;
+
+            public function replace(string $uid) {
+                return $this->replaceUidWithLink($uid);
+            }
+        };
+
+        $result = $xref->replace($uid);
+        $this->assertEquals($expected, $result);
+    }
+
     /**
      * @dataProvider provideReplaceProtoRefWithXref
      */

diff --git a/dev/tests/fixtures/docfx/NewClient/V1.Client.SecretManagerServiceClient.yml b/dev/tests/fixtures/docfx/NewClient/V1.Client.SecretManagerServiceClient.yml
@@ -604,7 +604,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::addSecretVersionAsync()'
     name: addSecretVersionAsync
@@ -625,7 +625,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::createSecretAsync()'
     name: createSecretAsync
@@ -646,7 +646,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::deleteSecretAsync()'
     name: deleteSecretAsync
@@ -667,7 +667,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::destroySecretVersionAsync()'
     name: destroySecretVersionAsync
@@ -688,7 +688,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::disableSecretVersionAsync()'
     name: disableSecretVersionAsync
@@ -709,7 +709,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::enableSecretVersionAsync()'
     name: enableSecretVersionAsync
@@ -730,7 +730,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::getIamPolicyAsync()'
     name: getIamPolicyAsync
@@ -751,7 +751,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::getSecretAsync()'
     name: getSecretAsync
@@ -772,7 +772,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::getSecretVersionAsync()'
     name: getSecretVersionAsync
@@ -793,7 +793,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::listSecretVersionsAsync()'
     name: listSecretVersionsAsync
@@ -814,7 +814,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::listSecretsAsync()'
     name: listSecretsAsync
@@ -835,7 +835,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::setIamPolicyAsync()'
     name: setIamPolicyAsync
@@ -856,7 +856,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::testIamPermissionsAsync()'
     name: testIamPermissionsAsync
@@ -877,7 +877,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::updateSecretAsync()'
     name: updateSecretAsync
@@ -898,7 +898,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::projectName()'
     name: 'static::projectName'

diff --git a/dev/tests/fixtures/docfx/Vision/V1.Client.ImageAnnotatorClient.yml b/dev/tests/fixtures/docfx/Vision/V1.Client.ImageAnnotatorClient.yml
@@ -244,7 +244,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\Vision\V1\Client\ImageAnnotatorClient::asyncBatchAnnotateImagesAsync()'
     name: asyncBatchAnnotateImagesAsync
@@ -265,7 +265,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\Vision\V1\Client\ImageAnnotatorClient::batchAnnotateFilesAsync()'
     name: batchAnnotateFilesAsync
@@ -286,7 +286,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\Vision\V1\Client\ImageAnnotatorClient::batchAnnotateImagesAsync()'
     name: batchAnnotateImagesAsync
@@ -307,7 +307,7 @@ items:
           description: ''
       returns:
         -
-          var_type: '<xref uid="\GuzzleHttp\Promise\PromiseInterface">GuzzleHttp\Promise\PromiseInterface</xref>'
+          var_type: '<a href="https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html">GuzzleHttp\Promise\PromiseInterface</a>'
   -
     uid: '\Google\Cloud\Vision\V1\Client\ImageAnnotatorClient::getOperationsClient()'
     name: getOperationsClient