Handle cyclic references for @inheritDoc

octogonz · octogonz · commit 96ee444de5aa · 2019-03-26T10:32:21.000-07:00
diff --git a/apps/api-extractor/src/api/ExtractorMessageId.ts b/apps/api-extractor/src/api/ExtractorMessageId.ts
@@ -70,7 +70,12 @@ export const enum ExtractorMessageId {
    * will find a corresponding member from a base class (or implemented interface).  Until then, the tag
    * always needs an explicit declaration reference such as `{@inhertDoc MyBaseClass.sameMethod}`.
    */
-  UnresolvedInheritDocBase = 'ae-unresolved-inheritdoc-base'
+  UnresolvedInheritDocBase = 'ae-unresolved-inheritdoc-base',
+
+  /**
+   * "The `@inheritDoc` tag for ____ refers to its own declaration".
+   */
+  CyclicInheritDoc = 'ae-cyclic-inherit-doc'
 }
 
 export const allExtractorMessageIds: Set<string> = new Set<string>([
@@ -84,5 +89,6 @@ export const allExtractorMessageIds: Set<string> = new Set<string>([
   'ae-preapproved-unsupported-type',
   'ae-preapproved-bad-release-tag',
   'ae-unresolved-inheritdoc-reference',
-  'ae-unresolved-inheritdoc-base'
+  'ae-unresolved-inheritdoc-base',
+  'ae-cyclic-inherit-doc'
 ]);
diff --git a/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts b/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts
@@ -9,7 +9,6 @@ import { AstSymbol } from '../analyzer/AstSymbol';
 import { AstDeclaration } from '../analyzer/AstDeclaration';
 import { DeclarationMetadata } from '../collector/DeclarationMetadata';
 import { AedocDefinitions } from '@microsoft/api-extractor-model';
-import { InternalError } from '@microsoft/node-core-library';
 import { ExtractorMessageId } from '../api/ExtractorMessageId';
 import { VisitorState } from '../collector/VisitorState';
 
@@ -44,7 +43,12 @@ export class DocCommentEnhancer {
     }
 
     if (metadata.docCommentEnhancerVisitorState === VisitorState.Visiting) {
-      throw new InternalError('Infinite loop in DocCommentEnhancer._analyzeDeclaration()');
+      this._collector.messageRouter.addAnalyzerIssue(
+        ExtractorMessageId.CyclicInheritDoc,
+        `The @inheritDoc tag for "${astDeclaration.astSymbol.localName}" refers to its own declaration`,
+        astDeclaration
+      );
+      return;
     }
     metadata.docCommentEnhancerVisitorState = VisitorState.Visiting;
 
diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/api-extractor-scenarios.api.json
@@ -189,6 +189,94 @@
             }
           ],
           "implementsTokenRanges": []
+        },
+        {
+          "kind": "Class",
+          "canonicalReference": "(FailWithSelfReference:class)",
+          "docComment": "/**\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare class "
+            },
+            {
+              "kind": "Reference",
+              "text": "FailWithSelfReference"
+            },
+            {
+              "kind": "Content",
+              "text": " "
+            }
+          ],
+          "releaseTag": "Public",
+          "name": "FailWithSelfReference",
+          "members": [
+            {
+              "kind": "Method",
+              "canonicalReference": "(method1:instance,0)",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Reference",
+                  "text": "method1"
+                },
+                {
+                  "kind": "Content",
+                  "text": "(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 2,
+                "endIndex": 3
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 0,
+              "parameters": [],
+              "name": "method1"
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "(method2:instance,0)",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Reference",
+                  "text": "method2"
+                },
+                {
+                  "kind": "Content",
+                  "text": "(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 2,
+                "endIndex": 3
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 0,
+              "parameters": [],
+              "name": "method2"
+            }
+          ],
+          "implementsTokenRanges": []
         }
       ]
     }
diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/api-extractor-scenarios.api.md b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/api-extractor-scenarios.api.md
@@ -16,6 +16,16 @@ export class CyclicB {
     methodB4(): void;
 }
 
+// @public (undocumented)
+export class FailWithSelfReference {
+    // Warning: (ae-cyclic-inherit-doc) The @inheritDoc tag for "method1" refers to its own declaration
+    // 
+    // (undocumented)
+    method1(): void;
+    // (undocumented)
+    method2(): void;
+}
+
 
 // (No @packageDocumentation comment for this package)
 
diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/rollup.d.ts
@@ -15,4 +15,12 @@ export declare class CyclicB {
     methodB4(): void;
 }
 
+/** @public */
+export declare class FailWithSelfReference {
+    /** {@inheritDoc FailWithSelfReference.method2} */
+    method1(): void;
+    /** {@inheritDoc FailWithSelfReference.method1} */
+    method2(): void;
+}
+
 export { }
diff --git a/build-tests/api-extractor-scenarios/src/docReferences2/index.ts b/build-tests/api-extractor-scenarios/src/docReferences2/index.ts
@@ -20,3 +20,13 @@ export class CyclicB {
   public methodB4(): void {
   }
 }
+
+/** @public */
+export class FailWithSelfReference {
+  /** {@inheritDoc FailWithSelfReference.method2} */
+  public method1(): void {
+  }
+  /** {@inheritDoc FailWithSelfReference.method1} */
+  public method2(): void {
+  }
+}
diff --git a/build-tests/api-extractor-scenarios/src/runScenarios.ts b/build-tests/api-extractor-scenarios/src/runScenarios.ts
@@ -66,6 +66,15 @@ export function runScenarios(buildConfigPath: string): void {
         "entryPointSourceFile": `./lib/${scenarioFolderName}/index.d.ts`
       },
 
+      "messages": {
+        "extractorMessageReporting": {
+          "ae-cyclic-inherit-doc": {
+            "logLevel": "warning",
+            "addToApiReviewFile": true
+          }
+        }
+      },
+
       "testMode": true
     };
 

Original file line number	Diff line number	Diff line change
`@@ -20,3 +20,13 @@ export class CyclicB {`
`20`	`20`	`public methodB4(): void {`
`21`	`21`	`}`
`22`	`22`	`}`
	`23`	`+`
	`24`	`+/** @public */`
	`25`	`+export class FailWithSelfReference {`
	`26`	`+ /** {@inheritDoc FailWithSelfReference.method2} */`
	`27`	`+ public method1(): void {`
	`28`	`+ }`
	`29`	`+ /** {@inheritDoc FailWithSelfReference.method1} */`
	`30`	`+ public method2(): void {`
	`31`	`+ }`
	`32`	`+}`