Fix handling of transitive @inheritDoc chains

octogonz · octogonz · commit c28e041cfcec · 2019-03-26T08:13:54.000-07:00
diff --git a/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts b/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts
@@ -10,7 +10,6 @@ import { AstDeclaration } from '../analyzer/AstDeclaration';
 import { DeclarationMetadata, VisitorState } from '../collector/DeclarationMetadata';
 import { AedocDefinitions } from '@microsoft/api-extractor-model';
 import { InternalError } from '@microsoft/node-core-library';
-import { ResultOrError } from '../analyzer/AstReferenceResolver';
 import { ExtractorMessageId } from '../api/ExtractorMessageId';
 
 export class DocCommentEnhancer {
@@ -41,8 +40,10 @@ export class DocCommentEnhancer {
     const metadata: DeclarationMetadata = this._collector.fetchMetadata(astDeclaration);
     if (metadata.docCommentEnhancerVisitorStage === VisitorState.Visited) {
       return;
-    } else if (metadata.docCommentEnhancerVisitorStage === VisitorState.Visiting) {
-      throw new InternalError('Infinite loop');
+    }
+
+    if (metadata.docCommentEnhancerVisitorStage === VisitorState.Visiting) {
+      throw new InternalError('Infinite loop in DocCommentEnhancer._analyzeDeclaration()');
     }
     metadata.docCommentEnhancerVisitorStage = VisitorState.Visiting;
 
@@ -51,6 +52,8 @@ export class DocCommentEnhancer {
     }
 
     this._analyzeNeedsDocumentation(astDeclaration, metadata);
+
+    metadata.docCommentEnhancerVisitorStage = VisitorState.Visited;
   }
 
   private _analyzeNeedsDocumentation(astDeclaration: AstDeclaration, metadata: DeclarationMetadata): void {
@@ -87,6 +90,9 @@ export class DocCommentEnhancer {
     }
   }
 
+  /**
+   * Follow an `{@inheritDoc ___}` reference and copy the content that we find in the referenced comment.
+   */
   private _analyzeInheritDoc(astDeclaration: AstDeclaration, docComment: tsdoc.DocComment,
     inheritDocTag: tsdoc.DocInheritDocTag): void {
 
@@ -97,22 +103,27 @@ export class DocCommentEnhancer {
       return;
     }
 
-    const sourceAstDeclaration: ResultOrError<AstDeclaration> = this._collector.astReferenceResolver
+    const referencedAstDeclaration: AstDeclaration | Error = this._collector.astReferenceResolver
       .resolve(inheritDocTag.declarationReference);
 
-    if (sourceAstDeclaration instanceof Error) {
+    if (referencedAstDeclaration instanceof Error) {
       this._collector.messageRouter.addAnalyzerIssue(ExtractorMessageId.UnresolvedInheritDocReference,
-        'The `@inheritDoc` reference could not be resolved: ' + sourceAstDeclaration.message, astDeclaration);
+        'The `@inheritDoc` reference could not be resolved: ' + referencedAstDeclaration.message, astDeclaration);
       return;
     }
 
-    const sourceMetadata: DeclarationMetadata = this._collector.fetchMetadata(sourceAstDeclaration);
+    this._analyzeDeclaration(referencedAstDeclaration);
+
+    const referencedMetadata: DeclarationMetadata = this._collector.fetchMetadata(referencedAstDeclaration);
 
-    if (sourceMetadata.tsdocComment) {
-      this._copyInheritedDocs(docComment, sourceMetadata.tsdocComment);
+    if (referencedMetadata.tsdocComment) {
+      this._copyInheritedDocs(docComment, referencedMetadata.tsdocComment);
     }
   }
 
+  /**
+   * Copy the content from `sourceDocComment` to `targetDocComment`.
+   */
   private _copyInheritedDocs(targetDocComment: tsdoc.DocComment, sourceDocComment: tsdoc.DocComment): void {
     targetDocComment.summarySection = sourceDocComment.summarySection;
     targetDocComment.remarksBlock = sourceDocComment.remarksBlock;
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
@@ -38,7 +38,7 @@
             {
               "kind": "Method",
               "canonicalReference": "(methodA1:instance,0)",
-              "docComment": "",
+              "docComment": "/**\n * THE COMMENT\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Reference",
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
@@ -6,7 +6,6 @@
 
 // @public (undocumented)
 export class CyclicA {
-    // (undocumented)
     methodA1(): void;
     methodA3(): void;
 }

Original file line number	Diff line number	Diff line change
`@@ -38,7 +38,7 @@`
`38`	`38`	`{`
`39`	`39`	`"kind": "Method",`
`40`	`40`	`"canonicalReference": "(methodA1:instance,0)",`
`41`		`- "docComment": "",`
	`41`	`+ "docComment": "/*\n THE COMMENT\n */\n",`
`42`	`42`	`"excerptTokens": [`
`43`	`43`	`{`
`44`	`44`	`"kind": "Reference",`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,6 @@`
`6`	`6`
`7`	`7`	`// @public (undocumented)`
`8`	`8`	`export class CyclicA {`
`9`		`- // (undocumented)`
`10`	`9`	`methodA1(): void;`
`11`	`10`	`methodA3(): void;`
`12`	`11`	`}`