Separate fetchMetadata() into fetchSymbolMetadata(), fetchDeclarationMetadata(), and fetchApiItemMetadata()

octogonz · octogonz · commit b48edc67f8fd · 2020-01-13T18:51:16.000-05:00
diff --git a/apps/api-extractor/src/analyzer/AstSymbol.ts b/apps/api-extractor/src/analyzer/AstSymbol.ts
@@ -109,7 +109,8 @@ export class AstSymbol {
 
   /**
    * Additional information that is calculated later by the `Collector`.  The actual type is `SymbolMetadata`,
-   * but we declare it as `unknown` because consumers must obtain this object by calling `Collector.fetchMetadata()`.
+   * but we declare it as `unknown` because consumers must obtain this object by calling
+   * `Collector.fetchSymbolMetadata()`.
    */
   public symbolMetadata: unknown;
 
diff --git a/apps/api-extractor/src/collector/ApiItemMetadata.ts b/apps/api-extractor/src/collector/ApiItemMetadata.ts
@@ -21,10 +21,10 @@ export interface IApiItemMetadataOptions {
 
 /**
  * Stores the Collector's additional analysis for an `AstDeclaration`.  This object is assigned to
- * `AstDeclaration.apiItemMetadata` but consumers must always obtain it by calling `Collector.fetchMetadata().
+ * `AstDeclaration.apiItemMetadata` but consumers must always obtain it by calling `Collector.fetchApiItemMetadata().
  *
  * Note that ancillary declarations share their `ApiItemMetadata` with the main declaration,
- * whereas a separate `DeclarationMetadata` object is created for each `AstDeclaration`.
+ * whereas a separate `DeclarationMetadata` object is created for each declaration.
  */
 export class ApiItemMetadata {
   /**
diff --git a/apps/api-extractor/src/collector/Collector.ts b/apps/api-extractor/src/collector/Collector.ts
@@ -231,7 +231,7 @@ export class Collector {
       this._createEntityForIndirectReferences(exportedAstEntity, alreadySeenAstSymbols);
 
       if (exportedAstEntity instanceof AstSymbol) {
-        this.fetchMetadata(exportedAstEntity);
+        this.fetchSymbolMetadata(exportedAstEntity);
       }
     }
 
@@ -270,21 +270,11 @@ export class Collector {
     return this._entitiesByAstEntity.get(astEntity);
   }
 
-  public fetchMetadata(astSymbol: AstSymbol): SymbolMetadata;
-  public fetchMetadata(astDeclaration: AstDeclaration): ApiItemMetadata;
-  public fetchMetadata(symbolOrDeclaration: AstSymbol | AstDeclaration): SymbolMetadata | ApiItemMetadata {
-    if (symbolOrDeclaration instanceof AstSymbol) {
-      if (symbolOrDeclaration.symbolMetadata === undefined) {
-        this._fetchSymbolMetadata(symbolOrDeclaration);
-      }
-      return symbolOrDeclaration.symbolMetadata as SymbolMetadata;
-    } else {
-      if (symbolOrDeclaration.apiItemMetadata === undefined) {
-        // Fetching the SymbolMetadata always constructs the ApiItemMetadata
-        this._fetchSymbolMetadata(symbolOrDeclaration.astSymbol);
-      }
-      return symbolOrDeclaration.apiItemMetadata as ApiItemMetadata;
+  public fetchSymbolMetadata(astSymbol: AstSymbol): SymbolMetadata {
+    if (astSymbol.symbolMetadata === undefined) {
+      this._fetchSymbolMetadata(astSymbol);
     }
+    return astSymbol.symbolMetadata as SymbolMetadata;
   }
 
   public fetchDeclarationMetadata(astDeclaration: AstDeclaration): DeclarationMetadata {
@@ -295,12 +285,20 @@ export class Collector {
     return astDeclaration.declarationMetadata as DeclarationMetadata;
   }
 
+  public fetchApiItemMetadata(astDeclaration: AstDeclaration): ApiItemMetadata {
+    if (astDeclaration.apiItemMetadata === undefined) {
+      // Fetching the SymbolMetadata always constructs the ApiItemMetadata
+      this._fetchSymbolMetadata(astDeclaration.astSymbol);
+    }
+    return astDeclaration.apiItemMetadata as ApiItemMetadata;
+  }
+
   public tryFetchMetadataForAstEntity(astEntity: AstEntity): SymbolMetadata | undefined {
     if (astEntity instanceof AstSymbol) {
-      return this.fetchMetadata(astEntity);
+      return this.fetchSymbolMetadata(astEntity);
     }
     if (astEntity.astSymbol) { // astImport
-      return this.fetchMetadata(astEntity.astSymbol);
+      return this.fetchSymbolMetadata(astEntity.astSymbol);
     }
     return undefined;
   }
@@ -778,7 +776,7 @@ export class Collector {
 
     // This needs to be set regardless of whether or not a parserContext exists
     if (astDeclaration.parent) {
-      const parentApiItemMetadata: ApiItemMetadata = this.fetchMetadata(astDeclaration.parent);
+      const parentApiItemMetadata: ApiItemMetadata = this.fetchApiItemMetadata(astDeclaration.parent);
       options.effectiveReleaseTag = options.declaredReleaseTag === ReleaseTag.None
         ? parentApiItemMetadata.effectiveReleaseTag
         : options.declaredReleaseTag;
diff --git a/apps/api-extractor/src/collector/DeclarationMetadata.ts b/apps/api-extractor/src/collector/DeclarationMetadata.ts
@@ -6,10 +6,11 @@ import { AstDeclaration } from '../analyzer/AstDeclaration';
 
 /**
  * Stores the Collector's additional analysis for a specific `AstDeclaration` signature.  This object is assigned to
- * `AstDeclaration.declarationMetadata` but consumers must always obtain it by calling `Collector.fetchDeclarationMetadata().
+ * `AstDeclaration.declarationMetadata` but consumers must always obtain it by calling
+ * `Collector.fetchDeclarationMetadata().
  *
  * Note that ancillary declarations share their `ApiItemMetadata` with the main declaration,
- * whereas a separate `DeclarationMetadata` object is created for each `AstDeclaration`.
+ * whereas a separate `DeclarationMetadata` object is created for each declaration.
  */
 export abstract class DeclarationMetadata {
   /**
diff --git a/apps/api-extractor/src/collector/SymbolMetadata.ts b/apps/api-extractor/src/collector/SymbolMetadata.ts
@@ -12,7 +12,7 @@ export interface ISymbolMetadataOptions {
 
 /**
  * Stores the Collector's additional analysis for an `AstSymbol`.  This object is assigned to `AstSymbol.metadata`
- * but consumers must always obtain it by calling `Collector.fetchMetadata().
+ * but consumers must always obtain it by calling `Collector.fetchSymbolMetadata().
  */
 export class SymbolMetadata {
   // For all declarations associated with this symbol, this is the
diff --git a/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts b/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts
@@ -38,7 +38,7 @@ export class DocCommentEnhancer {
   }
 
   private _analyzeDeclaration(astDeclaration: AstDeclaration): void {
-    const metadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+    const metadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
     if (metadata.docCommentEnhancerVisitorState === VisitorState.Visited) {
       return;
     }
@@ -92,10 +92,10 @@ export class DocCommentEnhancer {
         ]);
       }
 
-      const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       if (apiItemMetadata.effectiveReleaseTag === ReleaseTag.Internal) {
         // If the constructor is marked as internal, then add a boilerplate notice for the containing class
-        const classMetadata: ApiItemMetadata = this._collector.fetchMetadata(classDeclaration);
+        const classMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(classDeclaration);
 
         if (!classMetadata.tsdocComment) {
           classMetadata.tsdocComment = new tsdoc.DocComment({ configuration });
@@ -217,7 +217,7 @@ export class DocCommentEnhancer {
 
     this._analyzeDeclaration(referencedAstDeclaration);
 
-    const referencedMetadata: ApiItemMetadata = this._collector.fetchMetadata(referencedAstDeclaration);
+    const referencedMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(referencedAstDeclaration);
 
     if (referencedMetadata.tsdocComment) {
       this._copyInheritedDocs(docComment, referencedMetadata.tsdocComment);
diff --git a/apps/api-extractor/src/enhancers/ValidationEnhancer.ts b/apps/api-extractor/src/enhancers/ValidationEnhancer.ts
@@ -25,7 +25,7 @@ export class ValidationEnhancer {
             ValidationEnhancer._checkReferences(collector, astDeclaration, alreadyWarnedSymbols);
           });
 
-          const symbolMetadata: SymbolMetadata = collector.fetchMetadata(entity.astEntity);
+          const symbolMetadata: SymbolMetadata = collector.fetchSymbolMetadata(entity.astEntity);
           ValidationEnhancer._checkForInternalUnderscore(collector, entity, entity.astEntity, symbolMetadata);
           ValidationEnhancer._checkForInconsistentReleaseTags(collector, entity.astEntity, symbolMetadata);
         }
@@ -70,7 +70,7 @@ export class ValidationEnhancer {
         //     /** @internal */
         //     public static _Y(): void { }   // <==== different from parent
         //   }
-        const parentSymbolMetadata: SymbolMetadata = collector.fetchMetadata(astSymbol);
+        const parentSymbolMetadata: SymbolMetadata = collector.fetchSymbolMetadata(astSymbol);
         if (parentSymbolMetadata.maxEffectiveReleaseTag > ReleaseTag.Internal) {
           needsUnderscore = true;
         }
@@ -117,7 +117,7 @@ export class ValidationEnhancer {
     let anyInternalReleaseTags: boolean = false;
 
     for (const astDeclaration of astSymbol.astDeclarations) {
-      const apiItemMetadata: ApiItemMetadata = collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = collector.fetchApiItemMetadata(astDeclaration);
       const effectiveReleaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 
       switch (astDeclaration.declaration.kind) {
@@ -162,7 +162,7 @@ export class ValidationEnhancer {
     astDeclaration: AstDeclaration,
     alreadyWarnedSymbols: Set<AstSymbol>
   ): void {
-    const apiItemMetadata: ApiItemMetadata = collector.fetchMetadata(astDeclaration);
+    const apiItemMetadata: ApiItemMetadata = collector.fetchApiItemMetadata(astDeclaration);
     const declarationReleaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 
     for (const referencedEntity of astDeclaration.referencedAstEntities) {
@@ -178,7 +178,7 @@ export class ValidationEnhancer {
           const collectorEntity: CollectorEntity | undefined = collector.tryGetCollectorEntity(rootSymbol);
 
           if (collectorEntity && collectorEntity.exported) {
-            const referencedMetadata: SymbolMetadata = collector.fetchMetadata(referencedEntity);
+            const referencedMetadata: SymbolMetadata = collector.fetchSymbolMetadata(referencedEntity);
             const referencedReleaseTag: ReleaseTag = referencedMetadata.maxEffectiveReleaseTag;
 
             if (ReleaseTag.compare(declarationReleaseTag, referencedReleaseTag) > 0) {
diff --git a/apps/api-extractor/src/generators/ApiModelGenerator.ts b/apps/api-extractor/src/generators/ApiModelGenerator.ts
@@ -98,7 +98,7 @@ export class ApiModelGenerator {
       return; // trim out private declarations
     }
 
-    const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+    const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
     const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
     if (releaseTag === ReleaseTag.Internal || releaseTag === ReleaseTag.Alpha) {
       return; // trim out items marked as "@internal" or "@alpha"
@@ -208,7 +208,7 @@ export class ApiModelGenerator {
       const parameters: IApiParameterOptions[] = this._captureParameters(nodesToCapture, callSignature.parameters);
 
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
-      const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
       const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 
@@ -243,7 +243,7 @@ export class ApiModelGenerator {
         constructorDeclaration.parameters);
 
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
-      const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
       const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 
@@ -294,7 +294,7 @@ export class ApiModelGenerator {
       }
 
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
-      const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
       const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 
@@ -338,7 +338,7 @@ export class ApiModelGenerator {
       const parameters: IApiParameterOptions[] = this._captureParameters(nodesToCapture, constructSignature.parameters);
 
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
-      const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
       const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 
@@ -366,7 +366,7 @@ export class ApiModelGenerator {
 
     if (apiEnum === undefined) {
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, []);
-      const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
       const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 
@@ -394,7 +394,7 @@ export class ApiModelGenerator {
       nodesToCapture.push({ node: enumMember.initializer, tokenRange: initializerTokenRange });
 
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
-      const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
       const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 
@@ -436,7 +436,7 @@ export class ApiModelGenerator {
         functionDeclaration.parameters);
 
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
-      const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
       const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
       if (releaseTag === ReleaseTag.Internal || releaseTag === ReleaseTag.Alpha) {
@@ -478,7 +478,7 @@ export class ApiModelGenerator {
       const parameters: IApiParameterOptions[] = this._captureParameters(nodesToCapture, indexSignature.parameters);
 
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
-      const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
       const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 
@@ -524,7 +524,7 @@ export class ApiModelGenerator {
       }
 
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
-      const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
       const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 
@@ -568,7 +568,7 @@ export class ApiModelGenerator {
       const parameters: IApiParameterOptions[] = this._captureParameters(nodesToCapture, methodDeclaration.parameters);
 
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
-      const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
       const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
       if (releaseTag === ReleaseTag.Internal || releaseTag === ReleaseTag.Alpha) {
@@ -616,7 +616,7 @@ export class ApiModelGenerator {
       const parameters: IApiParameterOptions[] = this._captureParameters(nodesToCapture, methodSignature.parameters);
 
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
-      const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
       const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 
@@ -645,7 +645,7 @@ export class ApiModelGenerator {
 
     if (apiNamespace === undefined) {
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, []);
-      const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
       const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 
@@ -677,7 +677,7 @@ export class ApiModelGenerator {
       nodesToCapture.push({ node: propertyDeclaration.type, tokenRange: propertyTypeTokenRange });
 
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
-      const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
       const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 
@@ -707,7 +707,7 @@ export class ApiModelGenerator {
       nodesToCapture.push({ node: propertySignature.type, tokenRange: propertyTypeTokenRange });
 
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
-      const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
       const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 
@@ -748,7 +748,7 @@ export class ApiModelGenerator {
       nodesToCapture.push({ node: typeAliasDeclaration.type, tokenRange: typeTokenRange });
 
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
-      const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
       const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 
@@ -784,7 +784,7 @@ export class ApiModelGenerator {
       nodesToCapture.push({ node: variableDeclaration.type, tokenRange: variableTypeTokenRange });
 
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
-      const apiItemMetadata: ApiItemMetadata = this._collector.fetchMetadata(astDeclaration);
+      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
       const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
 
diff --git a/apps/api-extractor/src/generators/ApiReportGenerator.ts b/apps/api-extractor/src/generators/ApiReportGenerator.ts
diff --git a/apps/api-extractor/src/generators/DtsRollupGenerator.ts b/apps/api-extractor/src/generators/DtsRollupGenerator.ts
diff --git a/common/changes/@microsoft/api-extractor/octogonz-ae-issue-1679_2020-01-11-02-40.json b/common/changes/@microsoft/api-extractor/octogonz-ae-issue-1679_2020-01-11-02-40.json
