docs(docs-infra): Improve support for @link within the jsdoc. (#60201)

mmalerba · mmalerba · commit c615bdcde99c · 2025-03-04T17:13:43.000Z
PR Close #60201
diff --git a/adev/shared-docs/pipeline/api-gen/rendering/test/transforms/jsdoc-transforms.spec.ts b/adev/shared-docs/pipeline/api-gen/rendering/test/transforms/jsdoc-transforms.spec.ts
@@ -66,6 +66,18 @@ describe('jsdoc transforms', () => {
           name: 'see',
           comment: '{@link https://angular.dev}',
         },
+        {
+          name: 'see',
+          comment: '{@link /cli/build ng build}',
+        },
+        {
+          name: 'see',
+          comment: '{@link cli/build ng build}',
+        },
+        {
+          name: 'see',
+          comment: '{@link /ecosystem/rxjs-interop/output-interop Output Interop}',
+        },
       ],
       moduleName: 'test',
     });
@@ -117,5 +129,22 @@ describe('jsdoc transforms', () => {
       label: 'angular.dev',
       url: 'https://angular.dev',
     });
+
+    expect(entry.additionalLinks[10]).toEqual({
+      label: 'ng build',
+      url: '/cli/build',
+    });
+
+    // TODO: in the future when all links are valid we would throw an error instead when not starting with a slash
+    // Links should be absolute within adev (to support both next & stable site)
+    expect(entry.additionalLinks[11]).toEqual({
+      label: 'ng build',
+      url: 'cli/build',
+    });
+
+    expect(entry.additionalLinks[12]).toEqual({
+      label: 'Output Interop',
+      url: '/ecosystem/rxjs-interop/output-interop',
+    });
   });
 });
diff --git a/adev/shared-docs/pipeline/api-gen/rendering/transforms/jsdoc-transforms.ts b/adev/shared-docs/pipeline/api-gen/rendering/transforms/jsdoc-transforms.ts
@@ -195,10 +195,10 @@ function parseAtLink(link: string): {label: string; url: string} {
   let [rawSymbol, description] = link.split(/\s(.+)/);
   if (rawSymbol.startsWith('#')) {
     rawSymbol = rawSymbol.substring(1);
-  } else if (rawSymbol.startsWith('http://') || rawSymbol.startsWith('https://')) {
+  } else if (rawSymbol.includes('/')) {
     return {
       url: rawSymbol,
-      label: rawSymbol.split('/').pop()!,
+      label: description ?? rawSymbol.split('/').pop()!,
     };
   }
 
diff --git a/packages/core/src/util/is_dev_mode.ts b/packages/core/src/util/is_dev_mode.ts
@@ -13,7 +13,7 @@ import {global} from './global';
  *
  * By default, this is true, unless `enableProdMode` is invoked prior to calling this method or the
  * application is built using the Angular CLI with the `optimization` option.
- * @see {@link cli/build ng build}
+ * @see {@link /cli/build ng build}
  *
  * @publicApi
  */
@@ -31,7 +31,7 @@ export function isDevMode(): boolean {
  *
  * Using this method is discouraged as the Angular CLI will set production mode when using the
  * `optimization` option.
- * @see {@link cli/build ng build}
+ * @see {@link /cli/build ng build}
  *
  * @publicApi
  */

Original file line number	Diff line number	Diff line change
`@@ -13,7 +13,7 @@ import {global} from './global';`
`13`	`13`	`*`
`14`	`14`	* By default, this is true, unless `enableProdMode` is invoked prior to calling this method or the
`15`	`15`	* application is built using the Angular CLI with the `optimization` option.
`16`		`- * @see {@link cli/build ng build}`
	`16`	`+ * @see {@link /cli/build ng build}`
`17`	`17`	`*`
`18`	`18`	`* @publicApi`
`19`	`19`	`*/`
`@@ -31,7 +31,7 @@ export function isDevMode(): boolean {`
`31`	`31`	`*`
`32`	`32`	`* Using this method is discouraged as the Angular CLI will set production mode when using the`
`33`	`33`	* `optimization` option.
`34`		`- * @see {@link cli/build ng build}`
	`34`	`+ * @see {@link /cli/build ng build}`
`35`	`35`	`*`
`36`	`36`	`* @publicApi`
`37`	`37`	`*/`