[TASK] Rename method and improve doc comments

Author: linawolf

packages/guides/src/NodeRenderers/Html/MenuEntryRenderer.php

@@ -28,7 +28,7 @@ public function render(Node $node, RenderContext $renderContext): string
             $renderContext,
             'body/menu/menu-item.html.twig',
             [
-                'url' => $renderContext->relativeDocUrl($node->getUrl(), $node->getValue()->getId()),
+                'url' => $renderContext->generateCanonicalOutputUrl($node->getUrl(), $node->getValue()->getId()),
                 'node' => $node,
             ],
         );

packages/guides/src/ReferenceResolvers/DocReferenceResolver.php

@@ -25,7 +25,7 @@ public function resolve(LinkInlineNode $node, RenderContext $renderContext): boo
             return false;
         }
 
-        $node->setUrl($renderContext->relativeDocUrl($document->getFile()));
+        $node->setUrl($renderContext->generateCanonicalOutputUrl($document->getFile()));
         if ($node->getValue() === '') {
             $node->setValue($document->getTitle()->toString());
         }

packages/guides/src/ReferenceResolvers/RefReferenceResolver.php

@@ -23,7 +23,7 @@ public function resolve(LinkInlineNode $node, RenderContext $renderContext): boo
             return false;
         }
 
-        $node->setUrl($renderContext->relativeDocUrl($target->getDocumentPath(), $target->getAnchor()));
+        $node->setUrl($renderContext->generateCanonicalOutputUrl($target->getDocumentPath(), $target->getAnchor()));
         if ($node->getValue() === '') {
             $node->setValue($target->getTitle() ?? '');
         }

packages/guides/src/RenderContext.php

@@ -94,7 +94,10 @@ public function canonicalUrl(string $url): string
         return $this->urlGenerator->canonicalUrl($this->getDirName(), $url);
     }
 
-    public function relativeDocUrl(string $linkedDocument, string|null $anchor = null): string
+    /**
+     * Generate a canonical output URL with the configured file extension and anchor
+     */
+    public function generateCanonicalOutputUrl(string $linkedDocument, string|null $anchor = null): string
     {
         if ($this->projectNode->findDocumentEntry($linkedDocument) !== null) {
             // todo: this is a hack, existing documents are expected to be handled like absolute links in some places

packages/guides/src/Twig/AssetsExtension.php

@@ -114,7 +114,7 @@ public function renderNode(array $context, Node|array|null $node): string
     public function renderTarget(array $context, Target $target): string
     {
         if ($target instanceof InternalTarget) {
-            return $this->getRenderContext($context)->relativeDocUrl($target->getDocumentPath(), $target->getAnchor());
+            return $this->getRenderContext($context)->generateCanonicalOutputUrl($target->getDocumentPath(), $target->getAnchor());
         }
 
         return $target->getUrl();
@@ -146,7 +146,7 @@ public function renderMenu(array $context, string $menuType, int $maxMenuCount =
     /** @param array{env: RenderContext} $context */
     public function renderLink(array $context, string $url, string|null $anchor = null): string
     {
-        return $this->getRenderContext($context)->relativeDocUrl($url, $anchor);
+        return $this->getRenderContext($context)->generateCanonicalOutputUrl($url, $anchor);
     }
 
     private function copyAsset(

packages/guides/src/UrlGenerator.php

@@ -51,8 +51,6 @@ public function absoluteUrl(string $basePath, string $url): string
      * identifier to find the metadata for that file. Technically speaking, the canonical URL is the absolute URL
      * without the preceeding slash. But due to the many locations that this method is used; it will do its own
      * resolving.
-     *
-     * @todo simplify this method into the other methods or vice versa
      */
     public function canonicalUrl(string $basePath, string $url): string
     {
@@ -86,6 +84,10 @@ public function createFileUrl(string $filename, string $outputFormat = 'html', s
             ($anchor !== null ? '#' . $anchor : '');
     }
 
+    /**
+     * Generate a canonical output URL with file extension, anchor and prefixed by
+     * an absolute or relative path
+     */
     public function generateOutputUrlFromDocumentPath(
         string $currentDirectory,
         string $destinationPath,

packages/guides/src/UrlGeneratorInterface.php

@@ -21,8 +21,6 @@ public function absoluteUrl(string $basePath, string $url): string;
      * identifier to find the metadata for that file. Technically speaking, the canonical URL is the absolute URL
      * without the preceeding slash. But due to the many locations that this method is used; it will do its own
      * resolving.
-     *
-     * @todo simplify this method into the other methods or vice versa
      */
     public function canonicalUrl(string $basePath, string $url): string;
 
@@ -31,6 +29,10 @@ public function canonicalUrl(string $basePath, string $url): string;
      */
     public function createFileUrl(string $filename, string $outputFormat = 'html', string|null $anchor = null): string;
 
+    /**
+     * Generate a canonical output URL with file extension, anchor and prefixed by
+     * an absolute or relative path
+     */
     public function generateOutputUrlFromDocumentPath(
         string $currentDirectory,
         string $destinationPath,

packages/guides/tests/unit/RenderContextTest.php

@@ -43,7 +43,7 @@ public function testRelativeDocUrl(
             $projectNode,
         );
 
-        self::assertSame($result, $context->relativeDocUrl($linkedDocument, $anchor));
+        self::assertSame($result, $context->generateCanonicalOutputUrl($linkedDocument, $anchor));
     }
 
     /** @return string[][] */