feat(docs): use shortnames for references in the same namespace (#7822)

googleapis · Nov 14, 2024 · 2dc297e · 2dc297e
1 parent f687f8a
commit 2dc297e
Show file tree

Hide file tree

Showing 76 changed files with 402 additions and 388 deletions.
diff --git a/dev/src/DocFx/Node/ClassNode.php b/dev/src/DocFx/Node/ClassNode.php
@@ -33,7 +33,9 @@ class ClassNode
     public function __construct(
         private SimpleXMLElement $xmlNode,
         private array $protoPackages = [],
-    ) {}
+    ) {
+        $this->namespace = $this->getNamespace();
+    }
 
     public function isProtobufEnumClass(): bool
     {
@@ -173,7 +175,7 @@ public function getMethods(): array
     {
         $methods = [];
         foreach ($this->xmlNode->method as $methodNode) {
-            $method = new MethodNode($methodNode, $this->protoPackages);
+            $method = new MethodNode($methodNode, $this->namespace, $this->protoPackages);
             if ($method->isPublic() && !$method->isInherited() && !$method->isExcludedMethod()) {
                 // This is to fix an issue in phpdocumentor where magic methods do not have
                 // "inhereted_from" set as expected.
@@ -208,7 +210,7 @@ public function getConstants(): array
     {
         $constants = [];
         foreach ($this->xmlNode->constant as $constantNode) {
-            $constant = new ConstantNode($constantNode, $this->protoPackages);
+            $constant = new ConstantNode($constantNode, $this->namespace, $this->protoPackages);
             if ($constant->isPublic() && !$constant->isInherited()) {
                 $constants[] = $constant;
             }
@@ -237,7 +239,7 @@ public function setChildNode(ClassNode $childNode)
     public function getProtoPackage(): ?string
     {
         foreach ($this->xmlNode->constant as $constantNode) {
-            $constant = new ConstantNode($constantNode);
+            $constant = new ConstantNode($constantNode, $this->namespace, $this->protoPackages);
             if ($constant->getName() === 'SERVICE_NAME') {
                 // pop the service from the end to get the package name
                 $package = trim($constant->getValue(), '\'');

diff --git a/dev/src/DocFx/Node/ConstantNode.php b/dev/src/DocFx/Node/ConstantNode.php
@@ -30,7 +30,8 @@ class ConstantNode
 
     public function __construct(
         private SimpleXMLElement $xmlNode,
-        private array $protoPackages = []
+        private string $namespace,
+        private array $protoPackages
     ) {}
 
     public function getName(): string

diff --git a/dev/src/DocFx/Node/MethodNode.php b/dev/src/DocFx/Node/MethodNode.php
@@ -32,7 +32,8 @@ class MethodNode
 
     public function __construct(
         private SimpleXMLElement $xmlNode,
-        private array $protoPackages = []
+        private string $namespace,
+        private array $protoPackages,
     ) {}
 
     public function getReturnType(): string
@@ -122,7 +123,8 @@ public function getParameters(): array
             $parameter = new ParameterNode(
                 $parameterName,
                 (string) $parameterNode->type,
-                $this->replaceSeeTag($this->replaceProtoRef($description))
+                $this->replaceSeeTag($this->replaceProtoRef($description)),
+                $this->namespace
             );
 
             $parameters[] = $parameter;

diff --git a/dev/src/DocFx/Node/NameTrait.php b/dev/src/DocFx/Node/NameTrait.php
@@ -34,6 +34,6 @@ public function getFullname(): string
 
     public function getNamespace(): string
     {
-        return $this->xmlNode['namespace'];
+        return $this->xmlNode['namespace'] ?? '';
     }
 }
diff --git a/dev/src/DocFx/Node/ParameterNode.php b/dev/src/DocFx/Node/ParameterNode.php
@@ -29,7 +29,8 @@ class ParameterNode
     public function __construct(
         private string $name,
         private string $type,
-        private string $description
+        private string $description,
+        private string $namespace,
     ) {}
 
     public function getName(): string
@@ -107,7 +108,8 @@ public function getNestedParameters(): array
             $parameters[] = new ParameterNode(
                 $name,
                 $type,
-                $this->replaceSeeTag(trim($description))
+                $this->replaceSeeTag(trim($description)),
+                $this->namespace
             );
         }
 

diff --git a/dev/src/DocFx/Node/XrefTrait.php b/dev/src/DocFx/Node/XrefTrait.php
@@ -22,6 +22,8 @@
  */
 trait XrefTrait
 {
+    private string $namespace;
+
     /**
      * @param string $type The parameter type to replace
      */
@@ -156,8 +158,13 @@ function ($matches) {
 
     private function replaceUidWithLink(string $uid, string $name = null): string
     {
-        // Remove preceeding "\" from namespace
-        $name = $name ?: ltrim($uid, '\\');
+        if (is_null($name)) {
+            $name = ltrim($uid, '\\');
+            // Remove the namespace from the name if it matches the current namespace
+            if (!empty($this->namespace) && str_starts_with($uid, $this->namespace)) {
+                $name = substr($uid, strlen($this->namespace) + 1);
+            }
+        }
 
         // Case for generic types
         if (preg_match('/(.*)<(.*)>/', $uid, $matches)) {

diff --git a/dev/tests/Unit/DocFx/NodeTest.php b/dev/tests/Unit/DocFx/NodeTest.php
@@ -38,7 +38,7 @@ class NodeTest extends TestCase
     public function testNestedParameters()
     {
         $nestedParamsXml = file_get_contents(__DIR__ . '/../../fixtures/phpdoc/nestedparams.xml');
-        $method = new MethodNode(new SimpleXMLElement($nestedParamsXml));
+        $method = new MethodNode(new SimpleXMLElement($nestedParamsXml), '', []);
 
         $params = $method->getParameters();
 
@@ -81,7 +81,7 @@ public function testNestedParameters()
     public function testProtoRefInParameters()
     {
         $nestedParamsXml = file_get_contents(__DIR__ . '/../../fixtures/phpdoc/nestedparams.xml');
-        $method = new MethodNode(new SimpleXMLElement($nestedParamsXml));
+        $method = new MethodNode(new SimpleXMLElement($nestedParamsXml), '', []);
 
         $params = $method->getParameters();
 
@@ -126,7 +126,7 @@ public function testSeeTagsInMethodDescription()
 </docblock>
 </method>
 EOF;
-        $method = new MethodNode(new SimpleXMLElement($serviceXml));
+        $method = new MethodNode(new SimpleXMLElement($serviceXml), '', []);
 
         $content = $method->getContent();
         $this->assertStringContainsString(

diff --git a/dev/tests/fixtures/docfx/NewClient/V1.Client.SecretManagerServiceClient.yml b/dev/tests/fixtures/docfx/NewClient/V1.Client.SecretManagerServiceClient.yml
@@ -127,7 +127,7 @@ items:
       created <xref uid="\Google\Cloud\SecretManager\V1\SecretVersion">SecretVersion</xref>.
 
       The async variant is
-      <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::accessSecretVersionAsync()">Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::accessSecretVersionAsync()</xref> .
+      <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::accessSecretVersionAsync()">SecretManagerServiceClient::accessSecretVersionAsync()</xref> .
     parent: \Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient
     type: method
     langs:
@@ -217,7 +217,7 @@ items:
       containing secret data and attaches it to an existing
       <xref uid="\Google\Cloud\SecretManager\V1\Secret">Secret</xref>.
 
-      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::addSecretVersionAsync()">Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::addSecretVersionAsync()</xref>
+      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::addSecretVersionAsync()">SecretManagerServiceClient::addSecretVersionAsync()</xref>
       .
     parent: \Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient
     type: method
@@ -301,7 +301,7 @@ items:
       Creates a new <xref uid="\Google\Cloud\SecretManager\V1\Secret">Secret</xref> containing no
       <xref uid="\Google\Cloud\SecretManager\V1\SecretVersion">SecretVersions</xref>.
 
-      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::createSecretAsync()">Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::createSecretAsync()</xref> .
+      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::createSecretAsync()">SecretManagerServiceClient::createSecretAsync()</xref> .
     parent: \Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient
     type: method
     langs:
@@ -388,7 +388,7 @@ items:
     summary: |-
       Deletes a <xref uid="\Google\Cloud\SecretManager\V1\Secret">Secret</xref>.
 
-      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::deleteSecretAsync()">Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::deleteSecretAsync()</xref> .
+      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::deleteSecretAsync()">SecretManagerServiceClient::deleteSecretAsync()</xref> .
     parent: \Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient
     type: method
     langs:
@@ -467,7 +467,7 @@ items:
       and irrevocably destroys the secret data.
 
       The async variant is
-      <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::destroySecretVersionAsync()">Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::destroySecretVersionAsync()</xref> .
+      <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::destroySecretVersionAsync()">SecretManagerServiceClient::destroySecretVersionAsync()</xref> .
     parent: \Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient
     type: method
     langs:
@@ -555,7 +555,7 @@ items:
       <xref uid="\Google\Cloud\SecretManager\V1\SecretVersion\State::DISABLED">DISABLED</xref>.
 
       The async variant is
-      <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::disableSecretVersionAsync()">Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::disableSecretVersionAsync()</xref> .
+      <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::disableSecretVersionAsync()">SecretManagerServiceClient::disableSecretVersionAsync()</xref> .
     parent: \Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient
     type: method
     langs:
@@ -643,7 +643,7 @@ items:
       <xref uid="\Google\Cloud\SecretManager\V1\SecretVersion\State::ENABLED">ENABLED</xref>.
 
       The async variant is
-      <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::enableSecretVersionAsync()">Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::enableSecretVersionAsync()</xref> .
+      <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::enableSecretVersionAsync()">SecretManagerServiceClient::enableSecretVersionAsync()</xref> .
     parent: \Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient
     type: method
     langs:
@@ -728,7 +728,7 @@ items:
 
       Returns empty policy if the secret exists and does not have a policy set.
 
-      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::getIamPolicyAsync()">Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::getIamPolicyAsync()</xref> .
+      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::getIamPolicyAsync()">SecretManagerServiceClient::getIamPolicyAsync()</xref> .
     parent: \Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient
     type: method
     langs:
@@ -804,7 +804,7 @@ items:
     summary: |-
       Gets metadata for a given <xref uid="\Google\Cloud\SecretManager\V1\Secret">Secret</xref>.
 
-      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::getSecretAsync()">Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::getSecretAsync()</xref> .
+      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::getSecretAsync()">SecretManagerServiceClient::getSecretAsync()</xref> .
     parent: \Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient
     type: method
     langs:
@@ -886,7 +886,7 @@ items:
       `projects/*/secrets/*/versions/latest` is an alias to the most recently
       created <xref uid="\Google\Cloud\SecretManager\V1\SecretVersion">SecretVersion</xref>.
 
-      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::getSecretVersionAsync()">Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::getSecretVersionAsync()</xref>
+      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::getSecretVersionAsync()">SecretManagerServiceClient::getSecretVersionAsync()</xref>
       .
     parent: \Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient
     type: method
@@ -977,7 +977,7 @@ items:
       call does not return secret data.
 
       The async variant is
-      <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::listSecretVersionsAsync()">Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::listSecretVersionsAsync()</xref> .
+      <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::listSecretVersionsAsync()">SecretManagerServiceClient::listSecretVersionsAsync()</xref> .
     parent: \Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient
     type: method
     langs:
@@ -1061,7 +1061,7 @@ items:
     summary: |-
       Lists <xref uid="\Google\Cloud\SecretManager\V1\Secret">Secrets</xref>.
 
-      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::listSecretsAsync()">Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::listSecretsAsync()</xref> .
+      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::listSecretsAsync()">SecretManagerServiceClient::listSecretsAsync()</xref> .
     parent: \Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient
     type: method
     langs:
@@ -1150,7 +1150,7 @@ items:
       according to the policy set on the associated
       <xref uid="\Google\Cloud\SecretManager\V1\Secret">Secret</xref>.
 
-      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::setIamPolicyAsync()">Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::setIamPolicyAsync()</xref> .
+      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::setIamPolicyAsync()">SecretManagerServiceClient::setIamPolicyAsync()</xref> .
     parent: \Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient
     type: method
     langs:
@@ -1236,7 +1236,7 @@ items:
       may "fail open" without warning.
 
       The async variant is
-      <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::testIamPermissionsAsync()">Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::testIamPermissionsAsync()</xref> .
+      <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::testIamPermissionsAsync()">SecretManagerServiceClient::testIamPermissionsAsync()</xref> .
     parent: \Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient
     type: method
     langs:
@@ -1320,7 +1320,7 @@ items:
       Updates metadata of an existing
       <xref uid="\Google\Cloud\SecretManager\V1\Secret">Secret</xref>.
 
-      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::updateSecretAsync()">Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::updateSecretAsync()</xref> .
+      The async variant is <xref uid="\Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient::updateSecretAsync()">SecretManagerServiceClient::updateSecretAsync()</xref> .
     parent: \Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient
     type: method
     langs:

diff --git a/dev/tests/fixtures/docfx/Vision/V1.AddProductToProductSetRequest.yml b/dev/tests/fixtures/docfx/Vision/V1.AddProductToProductSetRequest.yml
@@ -139,7 +139,7 @@ items:
 
             Format is:
             `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID`
-            Please see <xref uid="\Google\Cloud\Vision\V1\ProductSearchClient::productSetName()">Google\Cloud\Vision\V1\ProductSearchClient::productSetName()</xref> for help formatting this field.
+            Please see <xref uid="\Google\Cloud\Vision\V1\ProductSearchClient::productSetName()">ProductSearchClient::productSetName()</xref> for help formatting this field.
         -
           id: product
           var_type: string
@@ -148,7 +148,7 @@ items:
 
             Format is:
             `projects/PROJECT_ID/locations/LOC_ID/products/PRODUCT_ID`
-            Please see <xref uid="\Google\Cloud\Vision\V1\ProductSearchClient::productName()">Google\Cloud\Vision\V1\ProductSearchClient::productName()</xref> for help formatting this field.
+            Please see <xref uid="\Google\Cloud\Vision\V1\ProductSearchClient::productName()">ProductSearchClient::productName()</xref> for help formatting this field.
       returns:
         -
-          var_type: '<xref uid="\Google\Cloud\Vision\V1\AddProductToProductSetRequest">Google\Cloud\Vision\V1\AddProductToProductSetRequest</xref>'
+          var_type: '<xref uid="\Google\Cloud\Vision\V1\AddProductToProductSetRequest">AddProductToProductSetRequest</xref>'
diff --git a/dev/tests/fixtures/docfx/Vision/V1.AnnotateFileRequest.yml b/dev/tests/fixtures/docfx/Vision/V1.AnnotateFileRequest.yml
@@ -44,15 +44,15 @@ items:
           description: 'Optional. Data for populating the Message object.'
         -
           id: '↳ input_config'
-          var_type: '<xref uid="\Google\Cloud\Vision\V1\InputConfig">Google\Cloud\Vision\V1\InputConfig</xref>'
+          var_type: '<xref uid="\Google\Cloud\Vision\V1\InputConfig">InputConfig</xref>'
           description: 'Required. Information about the input file.'
         -
           id: '↳ features'
-          var_type: 'array&lt;<xref uid="\Google\Cloud\Vision\V1\Feature">Google\Cloud\Vision\V1\Feature</xref>&gt;'
+          var_type: 'array&lt;<xref uid="\Google\Cloud\Vision\V1\Feature">Feature</xref>&gt;'
           description: 'Required. Requested features.'
         -
           id: '↳ image_context'
-          var_type: '<xref uid="\Google\Cloud\Vision\V1\ImageContext">Google\Cloud\Vision\V1\ImageContext</xref>'
+          var_type: '<xref uid="\Google\Cloud\Vision\V1\ImageContext">ImageContext</xref>'
           description: 'Additional context that may accompany the image(s) in the file.'
         -
           id: '↳ pages'
@@ -70,7 +70,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<xref uid="\Google\Cloud\Vision\V1\InputConfig">Google\Cloud\Vision\V1\InputConfig</xref>|null'
+          var_type: '<xref uid="\Google\Cloud\Vision\V1\InputConfig">InputConfig</xref>|null'
   -
     uid: '\Google\Cloud\Vision\V1\AnnotateFileRequest::hasInputConfig()'
     name: hasInputConfig
@@ -100,7 +100,7 @@ items:
       parameters:
         -
           id: var
-          var_type: '<xref uid="\Google\Cloud\Vision\V1\InputConfig">Google\Cloud\Vision\V1\InputConfig</xref>'
+          var_type: '<xref uid="\Google\Cloud\Vision\V1\InputConfig">InputConfig</xref>'
           description: ''
       returns:
         -
@@ -131,7 +131,7 @@ items:
       parameters:
         -
           id: var
-          var_type: 'array&lt;<xref uid="\Google\Cloud\Vision\V1\Feature">Google\Cloud\Vision\V1\Feature</xref>&gt;'
+          var_type: 'array&lt;<xref uid="\Google\Cloud\Vision\V1\Feature">Feature</xref>&gt;'
           description: ''
       returns:
         -
@@ -148,7 +148,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<xref uid="\Google\Cloud\Vision\V1\ImageContext">Google\Cloud\Vision\V1\ImageContext</xref>|null'
+          var_type: '<xref uid="\Google\Cloud\Vision\V1\ImageContext">ImageContext</xref>|null'
   -
     uid: '\Google\Cloud\Vision\V1\AnnotateFileRequest::hasImageContext()'
     name: hasImageContext
@@ -178,7 +178,7 @@ items:
       parameters:
         -
           id: var
-          var_type: '<xref uid="\Google\Cloud\Vision\V1\ImageContext">Google\Cloud\Vision\V1\ImageContext</xref>'
+          var_type: '<xref uid="\Google\Cloud\Vision\V1\ImageContext">ImageContext</xref>'
           description: ''
       returns:
         -