fix(docs-infra): don't link API symbols inside code comments

Identifiers mentioned inside code comments in docs-code blocks were
incorrectly turned into API links (for example, `// CanActivate ...`
or `<!-- Component template -->` rendered the symbol as a link). Two
separate mechanisms produced these links, so both are fixed:

- `linkApiEntriesTransformer` runs a TypeScript scanner over the raw
  source regardless of language. It already skips `//` and `/* */`
  comments but not HTML comments, so identifiers inside `<!-- ... -->`
  were still linked. Compute HTML comment ranges using
  `/<!--[\s\S]*?-->/g` and skip identifier tokens that fall within
  those ranges.
- `processForApiLinks` links symbols in every leaf span at the DOM
  level. Skip comment-colored spans and track `<!--`/`-->` delimiters
  across spans so text inside split HTML comments is not linked.

Author: MeAkib

adev/shared-docs/pipeline/shared/marked/extensions/docs-code/format/index.mts

@@ -67,14 +67,41 @@ export function formatCode(token: CodeToken, context: RendererContext): string {
   return containerEl.outerHTML;
 }
 
+/** Shiki comment color for the configured github-light / github-dark themes. */
+const COMMENT_COLOR = '#6A737D';
+
 /**
  * Process a DOM element to find spans (created by Shiki) and converts them to API links if they match entries.
  */
 export function processForApiLinks(fragment: Element, apiEntries: ApiEntries): void {
   const spans = fragment.querySelectorAll('span:not(:has(span))');
 
+  // Shiki may split an HTML/template comment (`<!-- ... -->`) across several
+  // sibling spans whose inner text is NOT comment-colored, so a per-span color
+  // check cannot detect it. Track the open/close delimiters across spans instead.
+  let insideHtmlComment = false;
+
   spans.forEach((span) => {
-    const symbolMatch = span.textContent?.match(/^(.*?)(\w+)(.*)$/);
+    const text = span.textContent ?? '';
+
+    const opensComment = text.includes('<!--');
+    const closesComment = text.includes('-->');
+
+    if (opensComment) {
+      insideHtmlComment = true;
+    }
+
+    // Whether this span sits within an HTML comment (covers the opening,
+    // closing, and any spans in between).
+    const skip = insideHtmlComment || isCommentSpan(span);
+
+    if (closesComment) {
+      insideHtmlComment = false;
+    }
+
+    if (skip) return;
+
+    const symbolMatch = text.match(/^(.*?)(\w+)(.*)$/);
     if (!symbolMatch) return;
 
     // Yes, index 0 is not interesting for us here
@@ -95,6 +122,13 @@ export function processForApiLinks(fragment: Element, apiEntries: ApiEntries): v
   });
 }
 
+/** Returns whether a Shiki-generated span represents a code comment. */
+function isCommentSpan(span: Element): boolean {
+  const style = span.getAttribute('style');
+  if (!style) return false;
+  return style.toUpperCase().includes(COMMENT_COLOR.toUpperCase());
+}
+
 /** Build the header element if a header is provided in the token. */
 function buildHeaderElement(token: CodeToken) {
   let header = '';

adev/shared-docs/pipeline/shared/marked/test/docs-code/docs-code.md

@@ -7,10 +7,25 @@ this is code
 
 <docs-code header="src/locale/messages.fr.xlf (<trans-unit>)" path="./messages.fr.xlf" />
 
-<docs-code header="Property names should not be linked" language="ts">  
-const form = {  
-  state: ['']  
-};  
+<docs-code header="Property names should not be linked" language="ts">
+const form = {
+  state: ['']
+};
 </docs-code>
 
 <docs-code hideDollar code="echo 'hello world'" />
+
+<docs-code header="TS line comment should not be linked" language="ts">
+// CanActivateChild - protects all child routes
+const x = 1;
+</docs-code>
+
+<docs-code header="HTML comment (uniform color) should not be linked" language="html">
+<!-- Component template -->
+<div></div>
+</docs-code>
+
+<docs-code header="HTML comment (split delimiters) should not be linked" language="angular-html">
+<!-- Component template -->
+<div></div>
+</docs-code>

adev/shared-docs/pipeline/shared/marked/test/docs-code/docs-code.spec.mts

@@ -57,4 +57,19 @@ describe('markdown to html', () => {
     const codeBlock = markdownDocument.querySelectorAll('.docs-code')[5];
     expect(codeBlock.getAttribute('hideDollar')).toBe('true');
   });
+
+  it('should not link API symbols inside single-line (//) comments', () => {
+    const codeBlock = markdownDocument.querySelectorAll('code')[6];
+    expect(codeBlock?.innerHTML).not.toContain('href="/api/router/CanActivateChild"');
+  });
+
+  it('should not link API symbols inside HTML comments (uniform comment color)', () => {
+    const codeBlock = markdownDocument.querySelectorAll('code')[7];
+    expect(codeBlock?.innerHTML).not.toContain('href="/api/core/Component"');
+  });
+
+  it('should not link API symbols inside HTML comments (split delimiter color)', () => {
+    const codeBlock = markdownDocument.querySelectorAll('code')[8];
+    expect(codeBlock?.innerHTML).not.toContain('href="/api/core/Component"');
+  });
 });

adev/shared-docs/pipeline/shared/shiki.mts

@@ -84,6 +84,9 @@ function removeWhitespaceTransformer(): ShikiTransformer {
   };
 }
 
+/** Matches HTML/template comments, which the TypeScript scanner does not recognize. */
+const HTML_COMMENT_REGEX = /<!--[\s\S]*?-->/g;
+
 /** A custom transformer which adds a link to local API entries whenever a matching identifier is discovered in the code block. */
 function linkApiEntriesTransformer(apiEntries?: ApiEntries): ShikiTransformer {
   if (apiEntries === undefined) {
@@ -92,25 +95,36 @@ function linkApiEntriesTransformer(apiEntries?: ApiEntries): ShikiTransformer {
   return {
     preprocess(code, options) {
       options.decorations ??= [];
+
+      // Collect HTML/template comment ranges the TS scanner cannot see.
+      const commentRanges: Array<[number, number]> = [];
+      let match: RegExpExecArray | null;
+      HTML_COMMENT_REGEX.lastIndex = 0;
+      while ((match = HTML_COMMENT_REGEX.exec(code)) !== null) {
+        commentRanges.push([match.index, match.index + match[0].length]);
+      }
+      const isInsideHtmlComment = (start: number): boolean =>
+        commentRanges.some(([from, to]) => start >= from && start < to);
+
       scanner.setText(code);
       let token = scanner.scan();
 
       while (token !== ts.SyntaxKind.EndOfFileToken) {
         if (token === ts.SyntaxKind.Identifier) {
+          const tokenStart = scanner.getTokenStart();
           const symbolUrl = getSymbolUrl(scanner.getTokenText(), apiEntries);
-          if (symbolUrl !== undefined) {
+          if (symbolUrl !== undefined && !isInsideHtmlComment(tokenStart)) {
             options.decorations.push({
-              transform: (el) => {
+              transform: (el: any) => {
                 el.tagName = 'a';
                 el.properties['href'] = symbolUrl;
                 return el;
               },
-              start: scanner.getTokenStart(),
+              start: tokenStart,
               end: scanner.getTokenEnd(),
             });
           }
         }
-
         token = scanner.scan();
       }