From 3c82c64143c00027bd172a32670cbb9f75202823 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9ctor=20Mendoza?= Date: Wed, 30 Oct 2024 14:56:07 -0400 Subject: [PATCH] feat: support external links for Guzzle Promise Interface (#7778) --- dev/src/DocFx/Node/XrefTrait.php | 38 +++++++++++++------ dev/tests/Unit/DocFx/NodeTest.php | 36 ++++++++++++++++++ .../V1.Client.SecretManagerServiceClient.yml | 30 +++++++-------- .../Vision/V1.Client.ImageAnnotatorClient.yml | 8 ++-- .../Vision/V1.Client.ProductSearchClient.yml | 38 +++++++++---------- 5 files changed, 100 insertions(+), 50 deletions(-) diff --git a/dev/src/DocFx/Node/XrefTrait.php b/dev/src/DocFx/Node/XrefTrait.php index 30f2ddd90ffe..6b691a398b49 100644 --- 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('%s', $extLinkRoot . $path, $name); + if (str_starts_with($uid, '\Google')) { + $extLinkRoot .= str_replace(['::', '\\', '()'], ['#method_', '/'], $name); + } + return sprintf('%s', $extLinkRoot, $name); } return sprintf('%s', $uid, $name); diff --git a/dev/tests/Unit/DocFx/NodeTest.php b/dev/tests/Unit/DocFx/NodeTest.php index 67633fdf418a..310fe7fea7b1 100644 --- 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 = 'GuzzleHttp\Promise\PromiseInterface'; + $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 = 'GuzzleHttp\Promise\PromiseInterface'; + $expected .= '<Google\Cloud\AdvisoryNotifications\V1\Notification>'; + $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 index 192e38fe3899..2d1c121e642c 100644 --- 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: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::addSecretVersionAsync()' name: addSecretVersionAsync @@ -625,7 +625,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::createSecretAsync()' name: createSecretAsync @@ -646,7 +646,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::deleteSecretAsync()' name: deleteSecretAsync @@ -667,7 +667,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::destroySecretVersionAsync()' name: destroySecretVersionAsync @@ -688,7 +688,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::disableSecretVersionAsync()' name: disableSecretVersionAsync @@ -709,7 +709,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::enableSecretVersionAsync()' name: enableSecretVersionAsync @@ -730,7 +730,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::getIamPolicyAsync()' name: getIamPolicyAsync @@ -751,7 +751,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::getSecretAsync()' name: getSecretAsync @@ -772,7 +772,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::getSecretVersionAsync()' name: getSecretVersionAsync @@ -793,7 +793,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::listSecretVersionsAsync()' name: listSecretVersionsAsync @@ -814,7 +814,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::listSecretsAsync()' name: listSecretsAsync @@ -835,7 +835,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::setIamPolicyAsync()' name: setIamPolicyAsync @@ -856,7 +856,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::testIamPermissionsAsync()' name: testIamPermissionsAsync @@ -877,7 +877,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::updateSecretAsync()' name: updateSecretAsync @@ -898,7 +898,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - 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 index 08aafe34a931..194ad2a2e434 100644 --- 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: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ImageAnnotatorClient::asyncBatchAnnotateImagesAsync()' name: asyncBatchAnnotateImagesAsync @@ -265,7 +265,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ImageAnnotatorClient::batchAnnotateFilesAsync()' name: batchAnnotateFilesAsync @@ -286,7 +286,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ImageAnnotatorClient::batchAnnotateImagesAsync()' name: batchAnnotateImagesAsync @@ -307,7 +307,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ImageAnnotatorClient::getOperationsClient()' name: getOperationsClient diff --git a/dev/tests/fixtures/docfx/Vision/V1.Client.ProductSearchClient.yml b/dev/tests/fixtures/docfx/Vision/V1.Client.ProductSearchClient.yml index 60651c60739a..4c6a63cd900b 100644 --- a/dev/tests/fixtures/docfx/Vision/V1.Client.ProductSearchClient.yml +++ b/dev/tests/fixtures/docfx/Vision/V1.Client.ProductSearchClient.yml @@ -826,7 +826,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::createProductAsync()' name: createProductAsync @@ -847,7 +847,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::createProductSetAsync()' name: createProductSetAsync @@ -868,7 +868,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::createReferenceImageAsync()' name: createReferenceImageAsync @@ -889,7 +889,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::deleteProductAsync()' name: deleteProductAsync @@ -910,7 +910,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::deleteProductSetAsync()' name: deleteProductSetAsync @@ -931,7 +931,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::deleteReferenceImageAsync()' name: deleteReferenceImageAsync @@ -952,7 +952,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::getProductAsync()' name: getProductAsync @@ -973,7 +973,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::getProductSetAsync()' name: getProductSetAsync @@ -994,7 +994,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::getReferenceImageAsync()' name: getReferenceImageAsync @@ -1015,7 +1015,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::importProductSetsAsync()' name: importProductSetsAsync @@ -1036,7 +1036,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::listProductSetsAsync()' name: listProductSetsAsync @@ -1057,7 +1057,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::listProductsAsync()' name: listProductsAsync @@ -1078,7 +1078,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::listProductsInProductSetAsync()' name: listProductsInProductSetAsync @@ -1099,7 +1099,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::listReferenceImagesAsync()' name: listReferenceImagesAsync @@ -1120,7 +1120,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::purgeProductsAsync()' name: purgeProductsAsync @@ -1141,7 +1141,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::removeProductFromProductSetAsync()' name: removeProductFromProductSetAsync @@ -1162,7 +1162,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::updateProductAsync()' name: updateProductAsync @@ -1183,7 +1183,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::updateProductSetAsync()' name: updateProductSetAsync @@ -1204,7 +1204,7 @@ items: description: '' returns: - - var_type: 'GuzzleHttp\Promise\PromiseInterface' + var_type: 'GuzzleHttp\Promise\PromiseInterface' - uid: '\Google\Cloud\Vision\V1\Client\ProductSearchClient::getOperationsClient()' name: getOperationsClient