Add some code comments

octogonz · octogonz · commit 341af7ef667a · 2019-03-25T21:06:29.000-07:00
diff --git a/apps/api-extractor/src/analyzer/AstModule.ts b/apps/api-extractor/src/analyzer/AstModule.ts
@@ -6,6 +6,9 @@ import * as ts from 'typescript';
 import { AstSymbol } from './AstSymbol';
 import { AstEntity } from './AstSymbolTable';
 
+/**
+ * Represents information collected by {@link AstSymbolTable.fetchAstModuleExportInfo}
+ */
 export class AstModuleExportInfo {
   public readonly exportedLocalEntities: Map<string, AstEntity> = new Map<string, AstEntity>();
   public readonly starExportedExternalModules: Set<AstModule> = new Set<AstModule>();
diff --git a/apps/api-extractor/src/analyzer/AstSymbolTable.ts b/apps/api-extractor/src/analyzer/AstSymbolTable.ts
@@ -106,10 +106,17 @@ export class AstSymbolTable {
     return this._exportAnalyzer.fetchAstModuleFromSourceFile(sourceFile, undefined);
   }
 
+  /**
+   * This crawls the specified entry point and collects the full set of exported AstSymbols.
+   */
   public fetchAstModuleExportInfo(astModule: AstModule): AstModuleExportInfo {
     return this._exportAnalyzer.fetchAstModuleExportInfo(astModule);
   }
 
+  /**
+   * Attempts to retrieve an export by name from the specified `AstModule`.
+   * Returns undefined if no match was found.
+   */
   public tryGetExportOfAstModule(exportName: string, astModule: AstModule): AstEntity | undefined {
     return this._exportAnalyzer.tryGetExportOfAstModule(exportName, astModule);
   }
diff --git a/apps/api-extractor/src/analyzer/ExportAnalyzer.ts b/apps/api-extractor/src/analyzer/ExportAnalyzer.ts
@@ -212,7 +212,7 @@ export class ExportAnalyzer {
   }
 
   /**
-   * This crawls the specified entry point and collects the full set of exported AstSymbols.
+   * Implementation of {@link AstSymbolTable.fetchAstModuleExportInfo}.
    */
   public fetchAstModuleExportInfo(entryPointAstModule: AstModule): AstModuleExportInfo {
     if (entryPointAstModule.isExternal) {
@@ -542,6 +542,9 @@ export class ExportAnalyzer {
     return astEntity;
   }
 
+  /**
+   * Implementation of {@link AstSymbolTable.tryGetExportOfAstModule}.
+   */
   public tryGetExportOfAstModule(exportName: string, astModule: AstModule): AstEntity | undefined {
     const visitedAstModules: Set<AstModule> = new Set<AstModule>();
     return this._tryGetExportOfAstModule(exportName, astModule,
diff --git a/apps/api-extractor/src/api/ExtractorMessageId.ts b/apps/api-extractor/src/api/ExtractorMessageId.ts
@@ -66,9 +66,9 @@ export const enum ExtractorMessageId {
    * "The `@inheritDoc` tag needs a TSDoc declaration reference; signature matching is not supported yet".
    *
    * @privateRemarks
-   * In the future, we can implement signature matching so that you can write `{@inheritDoc}` and API Extractor
-   * will find the corresponding member from a base class (or implemented interface).  Until then, the tag needs
-   * an explicit declaration reference such as `{@inhertDoc MyBaseClass.sameMethod}`.
+   * In the future, we will implement signature matching so that you can write `{@inheritDoc}` and API Extractor
+   * 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'
 }

Original file line number	Diff line number	Diff line change
`@@ -106,10 +106,17 @@ export class AstSymbolTable {`
`106`	`106`	`return this._exportAnalyzer.fetchAstModuleFromSourceFile(sourceFile, undefined);`
`107`	`107`	`}`
`108`	`108`
	`109`	`+ /**`
	`110`	`+ * This crawls the specified entry point and collects the full set of exported AstSymbols.`
	`111`	`+ */`
`109`	`112`	`public fetchAstModuleExportInfo(astModule: AstModule): AstModuleExportInfo {`
`110`	`113`	`return this._exportAnalyzer.fetchAstModuleExportInfo(astModule);`
`111`	`114`	`}`
`112`	`115`
	`116`	`+ /**`
	`117`	+ * Attempts to retrieve an export by name from the specified `AstModule`.
	`118`	`+ * Returns undefined if no match was found.`
	`119`	`+ */`
`113`	`120`	`public tryGetExportOfAstModule(exportName: string, astModule: AstModule): AstEntity \| undefined {`
`114`	`121`	`return this._exportAnalyzer.tryGetExportOfAstModule(exportName, astModule);`
`115`	`122`	`}`
Original file line number	Diff line number	Diff line change
`@@ -66,9 +66,9 @@ export const enum ExtractorMessageId {`
`66`	`66`	* "The `@inheritDoc` tag needs a TSDoc declaration reference; signature matching is not supported yet".
`67`	`67`	`*`
`68`	`68`	`* @privateRemarks`
`69`		- * In the future, we can implement signature matching so that you can write `{@inheritDoc}` and API Extractor
`70`		`- * will find the corresponding member from a base class (or implemented interface). Until then, the tag needs`
`71`		- * an explicit declaration reference such as `{@inhertDoc MyBaseClass.sameMethod}`.
	`69`	+ * In the future, we will implement signature matching so that you can write `{@inheritDoc}` and API Extractor
	`70`	`+ * will find a corresponding member from a base class (or implemented interface). Until then, the tag`
	`71`	+ * always needs an explicit declaration reference such as `{@inhertDoc MyBaseClass.sameMethod}`.
`72`	`72`	`*/`
`73`	`73`	`UnresolvedInheritDocBase = 'ae-unresolved-inheritdoc-base'`
`74`	`74`	`}`