fix(compiler-cli): escape angular control flow in jsdoc

AntonChesnokov · kirjs · commit 8d3a89a477e2 · 2025-11-25T11:33:29.000-05:00
Escape @-prefixed template control flow constructs during doc extraction so JSDoc parsing keeps description text intact. Add regression coverage for @for snippets. (cherry picked from commit 5bfa027)
diff --git a/packages/compiler-cli/src/ngtsc/docs/src/jsdoc_extractor.ts b/packages/compiler-cli/src/ngtsc/docs/src/jsdoc_extractor.ts
@@ -11,11 +11,11 @@ import ts from 'typescript';
 import {JsDocTagEntry} from './entities';
 
 /**
- * RegExp to match the `@` character follow by any Angular decorator, used to escape Angular
- * decorators in JsDoc blocks so that they're not parsed as JsDoc tags.
+ * RegExp to match the `@` character follow by any Angular decorator and control flow syntax, used to escape Angular
+ * decorators and control flow syntax in JsDoc blocks so that they're not parsed as JsDoc tags.
  */
-const decoratorExpression =
-  /@(?=(Injectable|Component|Directive|Pipe|NgModule|Input|Output|HostBinding|HostListener|Inject|Optional|Self|Host|SkipSelf|ViewChild|ViewChildren|ContentChild|ContentChildren))/g;
+const angularAtExpression =
+  /@(?=(Injectable|Component|Directive|Pipe|NgModule|Input|Output|HostBinding|HostListener|Inject|Optional|Self|Host|SkipSelf|ViewChild|ViewChildren|ContentChild|ContentChildren|if|else|for|switch|case|default|empty|defer|placeholder|loading|error|let)\b)/g;
 
 /** Gets the set of JsDoc tags applied to a node. */
 export function extractJsDocTags(node: ts.HasJSDoc): JsDocTagEntry[] {
@@ -79,12 +79,12 @@ function getEscapedNode(node: ts.HasJSDoc): ts.HasJSDoc {
   return file.statements.find((s) => ts.isClassDeclaration(s)) as ts.ClassDeclaration;
 }
 
-/** Escape the `@` character for Angular decorators. */
+/** Escape the `@` character for Angular decorators and template control flow syntax. */
 function escapeAngularDecorators(comment: string): string {
-  return comment.replace(decoratorExpression, '_NG_AT_');
+  return comment.replace(angularAtExpression, '_NG_AT_');
 }
 
-/** Unescapes the `@` character for Angular decorators. */
+/** Unescapes the `@` character for Angular decorators and template control flow syntax. */
 function unescapeAngularDecorators(comment: string): string {
   return comment.replace(/_NG_AT_/g, '@');
 }
diff --git a/packages/compiler-cli/test/ngtsc/doc_extraction/jsdoc_extraction_spec.ts b/packages/compiler-cli/test/ngtsc/doc_extraction/jsdoc_extraction_spec.ts
@@ -350,5 +350,45 @@ runInEachFileSystem(() => {
       expect(entry.jsdocTags.length).toBe(1);
       expect(entry.jsdocTags[0].name).toBe('deprecated');
     });
+
+    it('should escape Angular control flow syntax', () => {
+      env.write(
+        'index.ts',
+        `
+        /**
+         * Renders a list using Angular control flow.
+         *
+         * \`\`\`html
+         * @for (item of items; track item) {
+         *   @if (item.visible) {
+         *     <div>{{item.label}}</div>
+         *   } @else {
+         *     <span>Hidden</span>
+         *   }
+         *   @empty {
+         *     <div>No items</div>
+         *   }
+         * }
+         * \`\`\`
+         *
+         * @deprecated Use something else.
+         */
+        export class Example {}
+      `,
+      );
+
+      const docs: DocEntry[] = env.driveDocsExtraction('index.ts');
+      expect(docs.length).toBe(1);
+
+      const entry = docs[0] as ClassEntry;
+      expect(entry.description).toContain('@for (item of items; track item)');
+      expect(entry.description).toContain('@if (item.visible)');
+      expect(entry.description).toContain('@empty {');
+      expect(entry.jsdocTags.length).toBe(1);
+      expect(entry.jsdocTags[0]).toEqual({
+        name: 'deprecated',
+        comment: 'Use something else.',
+      });
+    });
   });
 });
