ApiModelGenerator.ts

// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
// See LICENSE in the project root for license information.

// tslint:disable:no-bitwise

import * as ts from 'typescript';
import * as tsdoc from '@microsoft/tsdoc';
import {
  ApiModel,
  ApiClass,
  ApiPackage,
  ApiEntryPoint,
  ApiMethod,
  ApiNamespace,
  ApiInterface,
  ApiItem,
  ApiDeclaredItem,
  ApiPropertySignature,
  ApiItemContainerMixin,
  ReleaseTag,
  ApiProperty,
  ApiMethodSignature,
  IApiParameterOptions,
  ApiEnum,
  ApiEnumMember,
  IExcerptTokenRange,
  ExcerptToken,
  ApiConstructor,
  ApiConstructSignature,
  ApiFunction,
  ApiIndexSignature,
  ApiVariable,
  ApiTypeAlias,
  ApiCallSignature
} from '@microsoft/api-extractor-model';

import { Collector } from '../collector/Collector';
import { AstDeclaration } from '../analyzer/AstDeclaration';
import { ExcerptBuilder, IExcerptBuilderNodeToCapture } from './ExcerptBuilder';
import { AstSymbol } from '../analyzer/AstSymbol';

export class ApiModelGenerator {
  private readonly _collector: Collector;
  private readonly _cachedOverloadIndexesByDeclaration: Map<AstDeclaration, number>;
  private readonly _apiModel: ApiModel;
  private readonly _excerptBuilder: ExcerptBuilder;
  /** Record the generated api items by corresponding symbol */
  private readonly _apiItemsBySymbol: Map<ts.Symbol, ApiItem> = new Map<ts.Symbol, ApiItem>();

  public constructor(collector: Collector) {
    this._collector = collector;
    this._cachedOverloadIndexesByDeclaration = new Map<AstDeclaration, number>();
    this._apiModel = new ApiModel();
    this._excerptBuilder = new ExcerptBuilder(this._collector.typeChecker);
  }

  public get apiModel(): ApiModel {
    return this._apiModel;
  }

  public buildApiPackage(): ApiPackage {
    const packageDocComment: tsdoc.DocComment | undefined = this._collector.workingPackage.tsdocComment;

    const apiPackage: ApiPackage = new ApiPackage({
      name: this._collector.workingPackage.name,
      docComment: packageDocComment
    });
    this._apiModel.addMember(apiPackage);

    const apiEntryPoint: ApiEntryPoint = new ApiEntryPoint({ name: '' });
    apiPackage.addMember(apiEntryPoint);

    // Create a CollectorEntity for each top-level export
    for (const entity of this._collector.entities) {
      if (entity.exported) {
        if (entity.astEntity instanceof AstSymbol) {
          for (const astDeclaration of entity.astEntity.astDeclarations) {
            this._processDeclaration(astDeclaration, entity.nameForEmit, apiEntryPoint);
          }
        } else {
          // TODO: Figure out how to represent reexported AstImport objects.  Basically we need to introduce a new
          // ApiItem subclass for "export alias", similar to a type alias, but representing declarations of the
          // form "export { X } from 'external-package'".  We can also use this to solve GitHub issue #950.
        }
      }
    }

    this._updateTokenApiReferences(apiPackage, this._excerptBuilder._tsSymbolsByToken);

    return apiPackage;
  }

  /**
   * Update the api item references for those "Reference" excerpt tokens.
   *
   * Note: right now, some references cannot be found, e.g.:
   *   - not-exported api items
   *   - not-parsed ts.Symbol (e.g. function Parameter, TypeParameter)
   */
  private _updateTokenApiReferences(apiPackage: ApiPackage,
    tsSymbolsByToken: ReadonlyMap<ExcerptToken, ts.Symbol>): void {

    const apiItemsBySymbol: Map<ts.Symbol, ApiItem> = this._apiItemsBySymbol;

    function forEachExcerptToken(excerptToken: ExcerptToken): void {
      const referencedSymbol: ts.Symbol|undefined = tsSymbolsByToken.get(excerptToken);
      const referencedApiItem: ApiItem|undefined = referencedSymbol && apiItemsBySymbol.get(referencedSymbol);
      if (referencedApiItem) {
        excerptToken.setReference(referencedApiItem.getDocDeclarationReference());
      }
    }

    function forEachApiItem(apiItem: ApiItem): void {
      if (apiItem instanceof ApiDeclaredItem) {
        apiItem.excerptTokens.forEach(forEachExcerptToken);
      }
      apiItem.members.forEach(forEachApiItem);
    }

    forEachApiItem(apiPackage);
  }

  private _processDeclaration(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {

    if ((astDeclaration.modifierFlags & ts.ModifierFlags.Private) !== 0) {
      return; // trim out private declarations
    }

    const releaseTag: ReleaseTag = this._collector.fetchMetadata(astDeclaration.astSymbol).releaseTag;
    if (releaseTag === ReleaseTag.Internal || releaseTag === ReleaseTag.Alpha) {
      return; // trim out items marked as "@internal" or "@alpha"
    }

    switch (astDeclaration.declaration.kind) {
      case ts.SyntaxKind.CallSignature:
        this._processApiCallSignature(astDeclaration, exportedName, parentApiItem);
        break;

      case ts.SyntaxKind.Constructor:
        this._processApiConstructor(astDeclaration, exportedName, parentApiItem);
        break;

      case ts.SyntaxKind.ConstructSignature:
        this._processApiConstructSignature(astDeclaration, exportedName, parentApiItem);
        break;

      case ts.SyntaxKind.ClassDeclaration:
        this._processApiClass(astDeclaration, exportedName, parentApiItem);
        break;

      case ts.SyntaxKind.EnumDeclaration:
        this._processApiEnum(astDeclaration, exportedName, parentApiItem);
        break;

      case ts.SyntaxKind.EnumMember:
        this._processApiEnumMember(astDeclaration, exportedName, parentApiItem);
        break;

      case ts.SyntaxKind.FunctionDeclaration:
        this._processApiFunction(astDeclaration, exportedName, parentApiItem);
        break;

      case ts.SyntaxKind.IndexSignature:
        this._processApiIndexSignature(astDeclaration, exportedName, parentApiItem);
        break;

      case ts.SyntaxKind.InterfaceDeclaration:
        this._processApiInterface(astDeclaration, exportedName, parentApiItem);
        break;

      case ts.SyntaxKind.MethodDeclaration:
        this._processApiMethod(astDeclaration, exportedName, parentApiItem);
        break;

      case ts.SyntaxKind.MethodSignature:
        this._processApiMethodSignature(astDeclaration, exportedName, parentApiItem);
        break;

      case ts.SyntaxKind.ModuleDeclaration:
        this._processApiNamespace(astDeclaration, exportedName, parentApiItem);
        break;

      case ts.SyntaxKind.PropertyDeclaration:
        this._processApiProperty(astDeclaration, exportedName, parentApiItem);
        break;

      case ts.SyntaxKind.PropertySignature:
        this._processApiPropertySignature(astDeclaration, exportedName, parentApiItem);
        break;

      case ts.SyntaxKind.TypeAliasDeclaration:
        this._processApiTypeAlias(astDeclaration, exportedName, parentApiItem);
        break;

      case ts.SyntaxKind.VariableDeclaration:
        this._processApiVariable(astDeclaration, exportedName, parentApiItem);
        break;

      default:
        // ignore unknown types
    }
  }

  private _processChildDeclarations(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {
    for (const childDeclaration of astDeclaration.children) {
      this._processDeclaration(childDeclaration, undefined, parentApiItem);
    }
  }

  private _processApiCallSignature(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {

    const overloadIndex: number = this._getOverloadIndex(astDeclaration);
    const canonicalReference: string = ApiCallSignature.getCanonicalReference(overloadIndex);

    let apiCallSignature: ApiCallSignature | undefined = parentApiItem.tryGetMember(canonicalReference) as
    ApiCallSignature;

    if (apiCallSignature === undefined) {
      const callSignature: ts.CallSignatureDeclaration = astDeclaration.declaration as ts.CallSignatureDeclaration;

      const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];

      const returnTypeTokenRange: IExcerptTokenRange = this._excerptBuilder.createEmptyTokenRange();
      nodesToCapture.push({ node: callSignature.type, tokenRange: returnTypeTokenRange });

      const parameters: IApiParameterOptions[] = this._captureParameters(nodesToCapture, callSignature.parameters);

      const excerptTokens: ExcerptToken[] = this._excerptBuilder.build({
        startingNode: astDeclaration.declaration,
        nodesToCapture
      });
      const docComment: tsdoc.DocComment | undefined = this._collector.fetchMetadata(astDeclaration).tsdocComment;
      const releaseTag: ReleaseTag = this._collector.fetchMetadata(astDeclaration.astSymbol).releaseTag;

      apiCallSignature = new ApiCallSignature({ docComment, releaseTag, parameters, overloadIndex,
        excerptTokens, returnTypeTokenRange });

      parentApiItem.addMember(apiCallSignature);
    }
  }

  private _processApiConstructor(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {

    const isStatic: boolean = (astDeclaration.modifierFlags & ts.ModifierFlags.Static) !== 0;
    const overloadIndex: number = this._getOverloadIndex(astDeclaration);
    const canonicalReference: string = ApiConstructor.getCanonicalReference(isStatic, overloadIndex);

    let apiConstructor: ApiConstructor | undefined = parentApiItem.tryGetMember(canonicalReference) as ApiConstructor;

    if (apiConstructor === undefined) {
      const constructorDeclaration: ts.ConstructorDeclaration = astDeclaration.declaration as ts.ConstructorDeclaration;

      const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];

      const parameters: IApiParameterOptions[] = this._captureParameters(nodesToCapture,
        constructorDeclaration.parameters);

      const excerptTokens: ExcerptToken[] = this._excerptBuilder.build({
        startingNode: astDeclaration.declaration,
        nodesToCapture
      });

      const docComment: tsdoc.DocComment | undefined = this._collector.fetchMetadata(astDeclaration).tsdocComment;
      const releaseTag: ReleaseTag = this._collector.fetchMetadata(astDeclaration.astSymbol).releaseTag;

      apiConstructor = new ApiConstructor({ docComment, releaseTag, isStatic, parameters, overloadIndex,
        excerptTokens });

      parentApiItem.addMember(apiConstructor);
    }
  }

  private _processApiClass(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {

    const name: string = !!exportedName ? exportedName : astDeclaration.astSymbol.localName;
    const canonicalReference: string = ApiClass.getCanonicalReference(name);

    let apiClass: ApiClass | undefined = parentApiItem.tryGetMember(canonicalReference) as ApiClass;

    if (apiClass === undefined) {
      const classDeclaration: ts.ClassDeclaration = astDeclaration.declaration as ts.ClassDeclaration;

      const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];
      let extendsTokenRange: IExcerptTokenRange | undefined = undefined;
      const implementsTokenRanges: IExcerptTokenRange[] = [];

      for (const heritageClause of classDeclaration.heritageClauses || []) {
        if (heritageClause.token === ts.SyntaxKind.ExtendsKeyword) {
          extendsTokenRange = this._excerptBuilder.createEmptyTokenRange();
          if (heritageClause.types.length > 0) {
            nodesToCapture.push({ node: heritageClause.types[0], tokenRange: extendsTokenRange});
          }
        } else if (heritageClause.token === ts.SyntaxKind.ImplementsKeyword) {
          for (const heritageType of heritageClause.types) {
            const implementsTokenRange: IExcerptTokenRange = this._excerptBuilder.createEmptyTokenRange();
            implementsTokenRanges.push(implementsTokenRange);
            nodesToCapture.push({ node: heritageType, tokenRange: implementsTokenRange});
          }
        }
      }

      const excerptTokens: ExcerptToken[] = this._excerptBuilder.build({
        startingNode: astDeclaration.declaration,
        stopBeforeChildKind: ts.SyntaxKind.FirstPunctuation,  // FirstPunctuation = "{"
        nodesToCapture
      });
      const docComment: tsdoc.DocComment | undefined = this._collector.fetchMetadata(astDeclaration).tsdocComment;
      const releaseTag: ReleaseTag = this._collector.fetchMetadata(astDeclaration.astSymbol).releaseTag;

      apiClass = new ApiClass({ name, docComment, releaseTag,
        excerptTokens, extendsTokenRange, implementsTokenRanges });

      parentApiItem.addMember(apiClass);
      this._apiItemsBySymbol.set(astDeclaration.astSymbol.followedSymbol, apiClass);
    }

    this._processChildDeclarations(astDeclaration, exportedName, apiClass);
  }

  private _processApiConstructSignature(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {

    const overloadIndex: number = this._getOverloadIndex(astDeclaration);
    const canonicalReference: string = ApiConstructSignature.getCanonicalReference(overloadIndex);

    let apiConstructSignature: ApiConstructSignature | undefined = parentApiItem.tryGetMember(canonicalReference) as
      ApiConstructSignature;

    if (apiConstructSignature === undefined) {
      const constructSignature: ts.ConstructSignatureDeclaration = astDeclaration.declaration as
        ts.ConstructSignatureDeclaration;

      const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];

      const returnTypeTokenRange: IExcerptTokenRange = this._excerptBuilder.createEmptyTokenRange();
      nodesToCapture.push({ node: constructSignature.type, tokenRange: returnTypeTokenRange });

      const parameters: IApiParameterOptions[] = this._captureParameters(nodesToCapture, constructSignature.parameters);

      const excerptTokens: ExcerptToken[] = this._excerptBuilder.build({
        startingNode: astDeclaration.declaration,
        nodesToCapture
      });
      const docComment: tsdoc.DocComment | undefined = this._collector.fetchMetadata(astDeclaration).tsdocComment;
      const releaseTag: ReleaseTag = this._collector.fetchMetadata(astDeclaration.astSymbol).releaseTag;

      apiConstructSignature = new ApiConstructSignature({ docComment, releaseTag, parameters, overloadIndex,
        excerptTokens, returnTypeTokenRange });

      parentApiItem.addMember(apiConstructSignature);
    }
  }

  private _processApiEnum(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {

    const name: string = !!exportedName ? exportedName : astDeclaration.astSymbol.localName;
    const canonicalReference: string = ApiEnum.getCanonicalReference(name);

    let apiEnum: ApiEnum | undefined = parentApiItem.tryGetMember(canonicalReference) as ApiEnum;

    if (apiEnum === undefined) {
      const excerptTokens: ExcerptToken[] = this._excerptBuilder.build({
        startingNode: astDeclaration.declaration,
        stopBeforeChildKind: ts.SyntaxKind.FirstPunctuation  // FirstPunctuation = "{"
      });

      const docComment: tsdoc.DocComment | undefined = this._collector.fetchMetadata(astDeclaration).tsdocComment;
      const releaseTag: ReleaseTag = this._collector.fetchMetadata(astDeclaration.astSymbol).releaseTag;

      apiEnum = new ApiEnum({ name, docComment, releaseTag, excerptTokens });
      parentApiItem.addMember(apiEnum);
      this._apiItemsBySymbol.set(astDeclaration.astSymbol.followedSymbol, apiEnum);
    }

    this._processChildDeclarations(astDeclaration, exportedName, apiEnum);
  }

  private _processApiEnumMember(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {

    const name: string = !!exportedName ? exportedName : astDeclaration.astSymbol.localName;
    const canonicalReference: string = ApiEnumMember.getCanonicalReference(name);

    let apiEnumMember: ApiEnumMember | undefined = parentApiItem.tryGetMember(canonicalReference) as ApiEnumMember;

    if (apiEnumMember === undefined) {
      const enumMember: ts.EnumMember = astDeclaration.declaration as ts.EnumMember;

      const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];

      const initializerTokenRange: IExcerptTokenRange = this._excerptBuilder.createEmptyTokenRange();
      nodesToCapture.push({ node: enumMember.initializer, tokenRange: initializerTokenRange });

      const excerptTokens: ExcerptToken[] = this._excerptBuilder.build({
        startingNode: astDeclaration.declaration,
        nodesToCapture
      });

      const docComment: tsdoc.DocComment | undefined = this._collector.fetchMetadata(astDeclaration).tsdocComment;
      const releaseTag: ReleaseTag = this._collector.fetchMetadata(astDeclaration.astSymbol).releaseTag;

      apiEnumMember = new ApiEnumMember({ name, docComment, releaseTag,
        excerptTokens, initializerTokenRange });

      parentApiItem.addMember(apiEnumMember);
      this._apiItemsBySymbol.set(astDeclaration.astSymbol.followedSymbol, apiEnumMember);
    }
  }

  private _processApiFunction(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {

    const name: string = !!exportedName ? exportedName : astDeclaration.astSymbol.localName;

    const overloadIndex: number = this._getOverloadIndex(astDeclaration);
    const canonicalReference: string = ApiFunction.getCanonicalReference(name, overloadIndex);

    let apiFunction: ApiFunction | undefined = parentApiItem.tryGetMember(canonicalReference) as
      ApiFunction;

    if (apiFunction === undefined) {
      const functionDeclaration: ts.FunctionDeclaration = astDeclaration.declaration as ts.FunctionDeclaration;

      const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];

      const returnTypeTokenRange: IExcerptTokenRange = this._excerptBuilder.createEmptyTokenRange();
      nodesToCapture.push({ node: functionDeclaration.type, tokenRange: returnTypeTokenRange });

      const parameters: IApiParameterOptions[] = this._captureParameters(nodesToCapture,
        functionDeclaration.parameters);

      const excerptTokens: ExcerptToken[] = this._excerptBuilder.build({
        startingNode: astDeclaration.declaration,
        nodesToCapture
      });
      const docComment: tsdoc.DocComment | undefined = this._collector.fetchMetadata(astDeclaration).tsdocComment;
      const releaseTag: ReleaseTag = this._collector.fetchMetadata(astDeclaration.astSymbol).releaseTag;

      apiFunction = new ApiFunction({ name, docComment, releaseTag, parameters, overloadIndex,
        excerptTokens, returnTypeTokenRange });

      parentApiItem.addMember(apiFunction);
    }
  }

  private _processApiIndexSignature(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {

    const overloadIndex: number = this._getOverloadIndex(astDeclaration);
    const canonicalReference: string = ApiIndexSignature.getCanonicalReference(overloadIndex);

    let apiIndexSignature: ApiIndexSignature | undefined = parentApiItem.tryGetMember(canonicalReference) as
    ApiIndexSignature;

    if (apiIndexSignature === undefined) {
      const indexSignature: ts.IndexSignatureDeclaration = astDeclaration.declaration as ts.IndexSignatureDeclaration;

      const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];

      const returnTypeTokenRange: IExcerptTokenRange = this._excerptBuilder.createEmptyTokenRange();
      nodesToCapture.push({ node: indexSignature.type, tokenRange: returnTypeTokenRange });

      const parameters: IApiParameterOptions[] = this._captureParameters(nodesToCapture, indexSignature.parameters);

      const excerptTokens: ExcerptToken[] = this._excerptBuilder.build({
        startingNode: astDeclaration.declaration,
        nodesToCapture
      });
      const docComment: tsdoc.DocComment | undefined = this._collector.fetchMetadata(astDeclaration).tsdocComment;
      const releaseTag: ReleaseTag = this._collector.fetchMetadata(astDeclaration.astSymbol).releaseTag;

      apiIndexSignature = new ApiIndexSignature({ docComment, releaseTag, parameters, overloadIndex,
        excerptTokens, returnTypeTokenRange });

      parentApiItem.addMember(apiIndexSignature);
    }
  }

  private _processApiInterface(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {

    const name: string = !!exportedName ? exportedName : astDeclaration.astSymbol.localName;
    const canonicalReference: string = ApiInterface.getCanonicalReference(name);

    let apiInterface: ApiInterface | undefined = parentApiItem.tryGetMember(canonicalReference) as ApiInterface;

    if (apiInterface === undefined) {
      const interfaceDeclaration: ts.InterfaceDeclaration = astDeclaration.declaration as ts.InterfaceDeclaration;

      const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];
      const extendsTokenRanges: IExcerptTokenRange[] = [];

      for (const heritageClause of interfaceDeclaration.heritageClauses || []) {
        if (heritageClause.token === ts.SyntaxKind.ExtendsKeyword) {
          for (const heritageType of heritageClause.types) {
            const extendsTokenRange: IExcerptTokenRange = this._excerptBuilder.createEmptyTokenRange();
            extendsTokenRanges.push(extendsTokenRange);
            nodesToCapture.push({ node: heritageType, tokenRange: extendsTokenRange});
          }
        }
      }

      const excerptTokens: ExcerptToken[] = this._excerptBuilder.build({
        startingNode: astDeclaration.declaration,
        stopBeforeChildKind: ts.SyntaxKind.FirstPunctuation,  // FirstPunctuation = "{"
        nodesToCapture
      });

      const docComment: tsdoc.DocComment | undefined = this._collector.fetchMetadata(astDeclaration).tsdocComment;
      const releaseTag: ReleaseTag = this._collector.fetchMetadata(astDeclaration.astSymbol).releaseTag;

      apiInterface = new ApiInterface({ name, docComment, releaseTag, excerptTokens, extendsTokenRanges });
      parentApiItem.addMember(apiInterface);
      this._apiItemsBySymbol.set(astDeclaration.astSymbol.followedSymbol, apiInterface);
    }

    this._processChildDeclarations(astDeclaration, exportedName, apiInterface);
  }

  private _processApiMethod(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {

    const name: string = !!exportedName ? exportedName : astDeclaration.astSymbol.localName;

    const isStatic: boolean = (astDeclaration.modifierFlags & ts.ModifierFlags.Static) !== 0;
    const overloadIndex: number = this._getOverloadIndex(astDeclaration);
    const canonicalReference: string = ApiMethod.getCanonicalReference(name, isStatic, overloadIndex);

    let apiMethod: ApiMethod | undefined = parentApiItem.tryGetMember(canonicalReference) as ApiMethod;

    if (apiMethod === undefined) {
      const methodDeclaration: ts.MethodDeclaration = astDeclaration.declaration as ts.MethodDeclaration;

      const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];

      const returnTypeTokenRange: IExcerptTokenRange = this._excerptBuilder.createEmptyTokenRange();
      nodesToCapture.push({ node: methodDeclaration.type, tokenRange: returnTypeTokenRange });

      const parameters: IApiParameterOptions[] = this._captureParameters(nodesToCapture, methodDeclaration.parameters);

      const excerptTokens: ExcerptToken[] = this._excerptBuilder.build({
        startingNode: astDeclaration.declaration,
        nodesToCapture
      });

      const docComment: tsdoc.DocComment | undefined = this._collector.fetchMetadata(astDeclaration).tsdocComment;
      const releaseTag: ReleaseTag = this._collector.fetchMetadata(astDeclaration.astSymbol).releaseTag;

      apiMethod = new ApiMethod({ name, docComment, releaseTag, isStatic, parameters, overloadIndex,
        excerptTokens, returnTypeTokenRange });

      parentApiItem.addMember(apiMethod);
      this._apiItemsBySymbol.set(astDeclaration.astSymbol.followedSymbol, apiMethod);
    }
  }

  private _processApiMethodSignature(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {

    const name: string = !!exportedName ? exportedName : astDeclaration.astSymbol.localName;

    const overloadIndex: number = this._getOverloadIndex(astDeclaration);
    const canonicalReference: string = ApiMethodSignature.getCanonicalReference(name, overloadIndex);

    let apiMethodSignature: ApiMethodSignature | undefined = parentApiItem.tryGetMember(canonicalReference) as
      ApiMethodSignature;

    if (apiMethodSignature === undefined) {
      const methodSignature: ts.MethodSignature = astDeclaration.declaration as ts.MethodSignature;

      const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];

      const returnTypeTokenRange: IExcerptTokenRange = this._excerptBuilder.createEmptyTokenRange();
      nodesToCapture.push({ node: methodSignature.type, tokenRange: returnTypeTokenRange });

      const parameters: IApiParameterOptions[] = this._captureParameters(nodesToCapture, methodSignature.parameters);

      const excerptTokens: ExcerptToken[] = this._excerptBuilder.build({
        startingNode: astDeclaration.declaration,
        nodesToCapture
      });
      const docComment: tsdoc.DocComment | undefined = this._collector.fetchMetadata(astDeclaration).tsdocComment;
      const releaseTag: ReleaseTag = this._collector.fetchMetadata(astDeclaration.astSymbol).releaseTag;

      apiMethodSignature = new ApiMethodSignature({ name, docComment, releaseTag, parameters, overloadIndex,
        excerptTokens, returnTypeTokenRange });

      parentApiItem.addMember(apiMethodSignature);
      this._apiItemsBySymbol.set(astDeclaration.astSymbol.followedSymbol, apiMethodSignature);
    }
  }

  private _processApiNamespace(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {

    const name: string = !!exportedName ? exportedName : astDeclaration.astSymbol.localName;
    const canonicalReference: string = ApiNamespace.getCanonicalReference(name);

    let apiNamespace: ApiNamespace | undefined = parentApiItem.tryGetMember(canonicalReference) as ApiNamespace;

    if (apiNamespace === undefined) {
      const excerptTokens: ExcerptToken[] = this._excerptBuilder.build({
        startingNode: astDeclaration.declaration,
        stopBeforeChildKind: ts.SyntaxKind.ModuleBlock  // ModuleBlock = the "{ ... }" block
      });

      const docComment: tsdoc.DocComment | undefined = this._collector.fetchMetadata(astDeclaration).tsdocComment;
      const releaseTag: ReleaseTag = this._collector.fetchMetadata(astDeclaration.astSymbol).releaseTag;

      apiNamespace = new ApiNamespace({ name, docComment, releaseTag, excerptTokens });
      parentApiItem.addMember(apiNamespace);
      this._apiItemsBySymbol.set(astDeclaration.astSymbol.followedSymbol, apiNamespace);
    }

    this._processChildDeclarations(astDeclaration, exportedName, apiNamespace);
  }

  private _processApiProperty(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {

    const name: string = !!exportedName ? exportedName : astDeclaration.astSymbol.localName;

    const isStatic: boolean = (astDeclaration.modifierFlags & ts.ModifierFlags.Static) !== 0;

    const canonicalReference: string = ApiProperty.getCanonicalReference(name, isStatic);

    let apiProperty: ApiProperty | undefined
      = parentApiItem.tryGetMember(canonicalReference) as ApiProperty;

    if (apiProperty === undefined) {
      const propertyDeclaration: ts.PropertyDeclaration = astDeclaration.declaration as ts.PropertyDeclaration;

      const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];

      const propertyTypeTokenRange: IExcerptTokenRange = this._excerptBuilder.createEmptyTokenRange();
      nodesToCapture.push({ node: propertyDeclaration.type, tokenRange: propertyTypeTokenRange });

      const excerptTokens: ExcerptToken[] = this._excerptBuilder.build({
        startingNode: astDeclaration.declaration,
        nodesToCapture
      });
      const docComment: tsdoc.DocComment | undefined = this._collector.fetchMetadata(astDeclaration).tsdocComment;
      const releaseTag: ReleaseTag = this._collector.fetchMetadata(astDeclaration.astSymbol).releaseTag;

      apiProperty = new ApiProperty({ name, docComment, releaseTag, isStatic, excerptTokens, propertyTypeTokenRange });
      parentApiItem.addMember(apiProperty);
      this._apiItemsBySymbol.set(astDeclaration.astSymbol.followedSymbol, apiProperty);
    } else {
      // If the property was already declared before (via a merged interface declaration),
      // we assume its signature is identical, because the language requires that.
    }
  }

  private _processApiPropertySignature(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {

    const name: string = !!exportedName ? exportedName : astDeclaration.astSymbol.localName;
    const canonicalReference: string = ApiPropertySignature.getCanonicalReference(name);

    let apiPropertySignature: ApiPropertySignature | undefined
      = parentApiItem.tryGetMember(canonicalReference) as ApiPropertySignature;

    if (apiPropertySignature === undefined) {
      const propertySignature: ts.PropertySignature = astDeclaration.declaration as ts.PropertySignature;

      const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];

      const propertyTypeTokenRange: IExcerptTokenRange = this._excerptBuilder.createEmptyTokenRange();
      nodesToCapture.push({ node: propertySignature.type, tokenRange: propertyTypeTokenRange });

      const excerptTokens: ExcerptToken[] = this._excerptBuilder.build({
        startingNode: astDeclaration.declaration,
        nodesToCapture
      });
      const docComment: tsdoc.DocComment | undefined = this._collector.fetchMetadata(astDeclaration).tsdocComment;
      const releaseTag: ReleaseTag = this._collector.fetchMetadata(astDeclaration.astSymbol).releaseTag;

      apiPropertySignature = new ApiPropertySignature({ name, docComment, releaseTag,
        excerptTokens, propertyTypeTokenRange });
      parentApiItem.addMember(apiPropertySignature);
      this._apiItemsBySymbol.set(astDeclaration.astSymbol.followedSymbol, apiPropertySignature);
    } else {
      // If the property was already declared before (via a merged interface declaration),
      // we assume its signature is identical, because the language requires that.
    }
  }

  private _processApiTypeAlias(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {

    const name: string = !!exportedName ? exportedName : astDeclaration.astSymbol.localName;

    const canonicalReference: string = ApiTypeAlias.getCanonicalReference(name);

    let apiTypeAlias: ApiTypeAlias | undefined = parentApiItem.tryGetMember(canonicalReference) as
      ApiTypeAlias;

    if (apiTypeAlias === undefined) {
      const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];

      const excerptTokens: ExcerptToken[] = this._excerptBuilder.build({
        startingNode: astDeclaration.declaration,
        nodesToCapture
      });
      const docComment: tsdoc.DocComment | undefined = this._collector.fetchMetadata(astDeclaration).tsdocComment;
      const releaseTag: ReleaseTag = this._collector.fetchMetadata(astDeclaration.astSymbol).releaseTag;

      apiTypeAlias = new ApiTypeAlias({ name, docComment, releaseTag, excerptTokens });

      parentApiItem.addMember(apiTypeAlias);
    }
  }

  private _processApiVariable(astDeclaration: AstDeclaration, exportedName: string | undefined,
    parentApiItem: ApiItemContainerMixin): void {

    const name: string = !!exportedName ? exportedName : astDeclaration.astSymbol.localName;

    const canonicalReference: string = ApiVariable.getCanonicalReference(name);

    let apiVariable: ApiVariable | undefined = parentApiItem.tryGetMember(canonicalReference) as
      ApiVariable;

    if (apiVariable === undefined) {
      const variableDeclaration: ts.VariableDeclaration = astDeclaration.declaration as ts.VariableDeclaration;

      const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];

      const variableTypeTokenRange: IExcerptTokenRange = this._excerptBuilder.createEmptyTokenRange();
      nodesToCapture.push({ node: variableDeclaration.type, tokenRange: variableTypeTokenRange });

      const excerptTokens: ExcerptToken[] = this._excerptBuilder.build({
        startingNode: astDeclaration.declaration,
        nodesToCapture
      });
      const docComment: tsdoc.DocComment | undefined = this._collector.fetchMetadata(astDeclaration).tsdocComment;
      const releaseTag: ReleaseTag = this._collector.fetchMetadata(astDeclaration.astSymbol).releaseTag;

      apiVariable = new ApiVariable({ name, docComment, releaseTag, excerptTokens, variableTypeTokenRange });

      parentApiItem.addMember(apiVariable);
    }
  }

  private _captureParameters(nodesToCapture: IExcerptBuilderNodeToCapture[],
    parameterNodes: ts.NodeArray<ts.ParameterDeclaration>): IApiParameterOptions[] {

    const parameters: IApiParameterOptions[] = [];
    for (const parameter of parameterNodes) {
      const parameterTypeTokenRange: IExcerptTokenRange = this._excerptBuilder.createEmptyTokenRange();
      nodesToCapture.push({ node: parameter.type, tokenRange: parameterTypeTokenRange });
      parameters.push({
        parameterName: parameter.name.getText().trim(),
        parameterTypeTokenRange
      });
    }
    return parameters;
  }

  private _getOverloadIndex(astDeclaration: AstDeclaration): number {
    const allDeclarations: ReadonlyArray<AstDeclaration> = astDeclaration.astSymbol.astDeclarations;
    if (allDeclarations.length === 1) {
      return 0; // trivial case
    }

    let overloadIndex: number | undefined = this._cachedOverloadIndexesByDeclaration.get(astDeclaration);

    if (overloadIndex === undefined) {
      let nextIndex: number = 0;
      for (const other of allDeclarations) {
        // Filter out other declarations that are not overloads.  For example, an overloaded function can also
        // be a namespace.
        if (other.declaration.kind === astDeclaration.declaration.kind) {
          this._cachedOverloadIndexesByDeclaration.set(other, nextIndex);
          ++nextIndex;
        }
      }
      overloadIndex = this._cachedOverloadIndexesByDeclaration.get(astDeclaration);
    }

    if (overloadIndex === undefined) {
      // This should never happen
      throw new Error('Error calculating overload index for declaration');
    }

    return overloadIndex;
  }
}