Merge pull request #1405 from microsoft/octogonz/ae-container-key

[api-extractor] Rename ApiItem.canonicalReference to ApiItem.containerKey

apps/api-documenter/package.json

@@ -18,7 +18,7 @@
     "@microsoft/api-extractor-model": "7.2.0",
     "@microsoft/node-core-library": "3.13.0",
     "@microsoft/ts-command-line": "4.2.6",
-    "@microsoft/tsdoc": "0.12.9",
+    "@microsoft/tsdoc": "0.12.10",
     "colors": "~1.2.1",
     "js-yaml": "~3.13.1"
   },

apps/api-extractor-model/package.json

@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "@microsoft/node-core-library": "3.13.0",
-    "@microsoft/tsdoc": "0.12.9",
+    "@microsoft/tsdoc": "0.12.10",
     "@types/node": "8.5.8"
   },
   "devDependencies": {

apps/api-extractor-model/src/items/ApiItem.ts

@@ -44,7 +44,6 @@ export interface IApiItemOptions {
 
 export interface IApiItemJson {
   kind: ApiItemKind;
-  canonicalReference: string;
 }
 
 /**
@@ -85,17 +84,28 @@ export class ApiItem {
   /** @virtual */
   public serializeInto(jsonObject: Partial<IApiItemJson>): void {
     jsonObject.kind = this.kind;
-    jsonObject.canonicalReference = this.canonicalReference;
   }
 
-  /** @virtual */
+  /**
+   * Identifies the subclass of the `ApiItem` base class.
+   * @virtual
+   */
   public get kind(): ApiItemKind {
     throw new Error('ApiItem.kind was not implemented by the child class');
   }
 
-  /** @virtual */
-  public get canonicalReference(): string {
-    throw new Error('ApiItem.canonicalReference was not implemented by the child class');
+  /**
+   * Returns a string key that can be used to efficiently retrieve an `ApiItem` from an `ApiItemContainerMixin`.
+   * The key is unique within the container.  Its format is undocumented and may change at any time.
+   *
+   * @remarks
+   * Use the `getContainerKey()` static member to construct the key.  Each subclass has a different implementation
+   * of this function, according to the aspects that are important for identifying it.
+   *
+   * @virtual
+   */
+  public get containerKey(): string {
+    throw new Error('ApiItem.containerKey was not implemented by the child class');
   }
 
   /**
@@ -203,7 +213,7 @@ export class ApiItem {
 
   /** @virtual */
   public getSortKey(): string {
-    return this.canonicalReference;
+    return this.containerKey;
   }
 }
 

apps/api-extractor-model/src/mixins/ApiItemContainerMixin.ts

@@ -19,7 +19,7 @@ export interface IApiItemContainerJson extends IApiItemJson {
 
 const _members: unique symbol = Symbol('ApiItemContainerMixin._members');
 const _membersSorted: unique symbol = Symbol('ApiItemContainerMixin._membersSorted');
-const _membersByCanonicalReference: unique symbol = Symbol('ApiItemContainerMixin._membersByCanonicalReference');
+const _membersByContainerKey: unique symbol = Symbol('ApiItemContainerMixin._membersByContainerKey');
 const _membersByName: unique symbol = Symbol('ApiItemContainerMixin._membersByName');
 
 /**
@@ -58,9 +58,15 @@ export interface ApiItemContainerMixin extends ApiItem {
   addMember(member: ApiItem): void;
 
   /**
-   * Attempts to retrieve a member using its canonicalReference, or returns undefined if no matching member was found.
+   * Attempts to retrieve a member using its containerKey, or returns `undefined` if no matching member was found.
+   *
+   * @remarks
+   * Use the `getContainerKey()` static member to construct the key.  Each subclass has a different implementation
+   * of this function, according to the aspects that are important for identifying it.
+   *
+   * See {@link ApiItem.containerKey} for more information.
    */
-  tryGetMember(canonicalReference: string): ApiItem | undefined;
+  tryGetMemberByKey(containerKey: string): ApiItem | undefined;
 
   /**
    * Returns a list of members with the specified name.
@@ -85,7 +91,7 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(ba
   abstract class MixedClass extends baseClass implements ApiItemContainerMixin {
     public readonly [_members]: ApiItem[];
     public [_membersSorted]: boolean;
-    public [_membersByCanonicalReference]: Map<string, ApiItem>;
+    public [_membersByContainerKey]: Map<string, ApiItem>;
     public [_membersByName]: Map<string, ApiItem[]> | undefined;
 
     /** @override */
@@ -106,7 +112,7 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(ba
       const options: IApiItemContainerMixinOptions = args[0] as IApiItemContainerMixinOptions;
 
       this[_members] = [];
-      this[_membersByCanonicalReference] = new Map<string, ApiItem>();
+      this[_membersByContainerKey] = new Map<string, ApiItem>();
 
       if (options.members) {
         for (const member of options.members) {
@@ -125,8 +131,8 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(ba
     }
 
     public addMember(member: ApiItem): void {
-      if (this[_membersByCanonicalReference].has(member.canonicalReference)) {
-        throw new Error('Another member has already been added with the same name and canonicalReference');
+      if (this[_membersByContainerKey].has(member.containerKey)) {
+        throw new Error('Another member has already been added with the same name and containerKey');
       }
 
       const existingParent: ApiItem | undefined = member[ApiItem_parent];
@@ -137,13 +143,13 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(ba
       this[_members].push(member);
       this[_membersByName] = undefined; // invalidate the lookup
       this[_membersSorted] = false;
-      this[_membersByCanonicalReference].set(member.canonicalReference, member);
+      this[_membersByContainerKey].set(member.containerKey, member);
 
       member[ApiItem_parent] = this;
     }
 
-    public tryGetMember(canonicalReference: string): ApiItem | undefined {
-      return this[_membersByCanonicalReference].get(canonicalReference);
+    public tryGetMemberByKey(containerKey: string): ApiItem | undefined {
+      return this[_membersByContainerKey].get(containerKey);
     }
 
     public findMembersByName(name: string): ReadonlyArray<ApiItem> {

apps/api-extractor-model/src/model/ApiCallSignature.ts

@@ -52,8 +52,8 @@ export interface IApiCallSignatureOptions extends
 export class ApiCallSignature extends ApiTypeParameterListMixin(ApiParameterListMixin(ApiReleaseTagMixin(
   ApiReturnTypeMixin(ApiDeclaredItem)))) {
 
-  public static getCanonicalReference(overloadIndex: number): string {
-    return `(:call,${overloadIndex})`;
+  public static getContainerKey(overloadIndex: number): string {
+    return `|${ApiItemKind.CallSignature}|${overloadIndex}`;
   }
 
   public constructor(options: IApiCallSignatureOptions) {
@@ -66,7 +66,7 @@ export class ApiCallSignature extends ApiTypeParameterListMixin(ApiParameterList
   }
 
   /** @override */
-  public get canonicalReference(): string {
-    return ApiCallSignature.getCanonicalReference(this.overloadIndex);
+  public get containerKey(): string {
+    return ApiCallSignature.getContainerKey(this.overloadIndex);
   }
 }

apps/api-extractor-model/src/model/ApiClass.ts

@@ -60,8 +60,8 @@ export class ApiClass extends ApiItemContainerMixin(ApiNameMixin(ApiTypeParamete
 
   private readonly _implementsTypes: HeritageType[] = [];
 
-  public static getCanonicalReference(name: string): string {
-    return `(${name}:class)`;
+  public static getContainerKey(name: string): string {
+    return `${name}|${ApiItemKind.Class}`;
   }
 
   /** @override */
@@ -94,8 +94,8 @@ export class ApiClass extends ApiItemContainerMixin(ApiNameMixin(ApiTypeParamete
   }
 
   /** @override */
-  public get canonicalReference(): string {
-    return ApiClass.getCanonicalReference(this.name);
+  public get containerKey(): string {
+    return ApiClass.getContainerKey(this.name);
   }
 
   /**

apps/api-extractor-model/src/model/ApiConstructSignature.ts

@@ -65,8 +65,8 @@ export interface IApiConstructSignatureOptions extends
 export class ApiConstructSignature extends ApiTypeParameterListMixin(ApiParameterListMixin(ApiReleaseTagMixin(
   ApiReturnTypeMixin(ApiDeclaredItem)))) {
 
-  public static getCanonicalReference(overloadIndex: number): string {
-    return `(:new,${overloadIndex})`;
+  public static getContainerKey(overloadIndex: number): string {
+    return `|${ApiItemKind.ConstructSignature}|${overloadIndex}`;
   }
 
   public constructor(options: IApiConstructSignatureOptions) {
@@ -79,7 +79,7 @@ export class ApiConstructSignature extends ApiTypeParameterListMixin(ApiParamete
   }
 
   /** @override */
-  public get canonicalReference(): string {
-    return ApiConstructSignature.getCanonicalReference(this.overloadIndex);
+  public get containerKey(): string {
+    return ApiConstructSignature.getContainerKey(this.overloadIndex);
   }
 }

apps/api-extractor-model/src/model/ApiConstructor.ts

@@ -45,8 +45,8 @@ export interface IApiConstructorOptions extends
  */
 export class ApiConstructor extends ApiParameterListMixin(ApiReleaseTagMixin(ApiDeclaredItem)) {
 
-  public static getCanonicalReference(overloadIndex: number): string {
-    return `(:constructor,${overloadIndex})`;
+  public static getContainerKey(overloadIndex: number): string {
+    return `|${ApiItemKind.Constructor}|${overloadIndex}`;
   }
 
   public constructor(options: IApiConstructorOptions) {
@@ -59,7 +59,7 @@ export class ApiConstructor extends ApiParameterListMixin(ApiReleaseTagMixin(Api
   }
 
   /** @override */
-  public get canonicalReference(): string {
-    return ApiConstructor.getCanonicalReference(this.overloadIndex);
+  public get containerKey(): string {
+    return ApiConstructor.getContainerKey(this.overloadIndex);
   }
 }

apps/api-extractor-model/src/model/ApiEntryPoint.ts

@@ -47,7 +47,8 @@ export class ApiEntryPoint extends ApiItemContainerMixin(ApiNameMixin(ApiItem))
   }
 
   /** @override */
-  public get canonicalReference(): string {
+  public get containerKey(): string {
+    // No prefix needed, because ApiEntryPoint is the only possible member of an ApiPackage
     return this.name;
   }
 }

apps/api-extractor-model/src/model/ApiEnum.ts

@@ -41,8 +41,8 @@ export interface IApiEnumOptions extends
  */
 export class ApiEnum extends ApiItemContainerMixin(ApiNameMixin(ApiReleaseTagMixin(ApiDeclaredItem))) {
 
-  public static getCanonicalReference(name: string): string {
-    return `(${name}:enum)`;
+  public static getContainerKey(name: string): string {
+    return `${name}|${ApiItemKind.Enum}`;
   }
 
   public constructor(options: IApiEnumOptions) {
@@ -60,8 +60,8 @@ export class ApiEnum extends ApiItemContainerMixin(ApiNameMixin(ApiReleaseTagMix
   }
 
   /** @override */
-  public get canonicalReference(): string {
-    return ApiEnum.getCanonicalReference(this.name);
+  public get containerKey(): string {
+    return ApiEnum.getContainerKey(this.name);
   }
 
   /** @override */

apps/api-extractor-model/src/model/ApiEnumMember.ts

@@ -50,7 +50,8 @@ export class ApiEnumMember extends ApiNameMixin(ApiReleaseTagMixin(ApiDeclaredIt
    */
   public readonly initializerExcerpt: Excerpt;
 
-  public static getCanonicalReference(name: string): string {
+  public static getContainerKey(name: string): string {
+    // No prefix needed, because ApiEnumMember is the only possible member of an ApiEnum
     return name;
   }
 
@@ -75,8 +76,8 @@ export class ApiEnumMember extends ApiNameMixin(ApiReleaseTagMixin(ApiDeclaredIt
   }
 
   /** @override */
-  public get canonicalReference(): string {
-    return ApiEnumMember.getCanonicalReference(this.name);
+  public get containerKey(): string {
+    return ApiEnumMember.getContainerKey(this.name);
   }
 
   /** @override */

apps/api-extractor-model/src/model/ApiFunction.ts

@@ -46,8 +46,8 @@ export interface IApiFunctionOptions extends
 export class ApiFunction extends ApiNameMixin(ApiTypeParameterListMixin(ApiParameterListMixin(ApiReleaseTagMixin(
   ApiReturnTypeMixin(ApiDeclaredItem))))) {
 
-  public static getCanonicalReference(name: string, overloadIndex: number): string {
-    return `(${name}:${overloadIndex})`;
+  public static getContainerKey(name: string, overloadIndex: number): string {
+    return `${name}|${ApiItemKind.Function}|${overloadIndex}`;
   }
 
   public constructor(options: IApiFunctionOptions) {
@@ -60,7 +60,7 @@ export class ApiFunction extends ApiNameMixin(ApiTypeParameterListMixin(ApiParam
   }
 
   /** @override */
-  public get canonicalReference(): string {
-    return ApiFunction.getCanonicalReference(this.name, this.overloadIndex);
+  public get containerKey(): string {
+    return ApiFunction.getContainerKey(this.name, this.overloadIndex);
   }
 }

apps/api-extractor-model/src/model/ApiIndexSignature.ts

@@ -42,8 +42,8 @@ export interface IApiIndexSignatureOptions extends
  */
 export class ApiIndexSignature extends ApiParameterListMixin(ApiReleaseTagMixin(ApiReturnTypeMixin(ApiDeclaredItem))) {
 
-  public static getCanonicalReference(overloadIndex: number): string {
-    return `(:index,${overloadIndex})`;
+  public static getContainerKey(overloadIndex: number): string {
+    return `|${ApiItemKind.IndexSignature}|${overloadIndex}`;
   }
 
   public constructor(options: IApiIndexSignatureOptions) {
@@ -56,7 +56,7 @@ export class ApiIndexSignature extends ApiParameterListMixin(ApiReleaseTagMixin(
   }
 
   /** @override */
-  public get canonicalReference(): string {
-    return ApiIndexSignature.getCanonicalReference(this.overloadIndex);
+  public get containerKey(): string {
+    return ApiIndexSignature.getContainerKey(this.overloadIndex);
   }
 }

apps/api-extractor-model/src/model/ApiInterface.ts

@@ -59,8 +59,8 @@ export class ApiInterface extends ApiItemContainerMixin(ApiNameMixin(ApiTypePara
 
   private readonly _extendsTypes: HeritageType[] = [];
 
-  public static getCanonicalReference(name: string): string {
-    return `(${name}:interface)`;
+  public static getContainerKey(name: string): string {
+    return `${name}|${ApiItemKind.Interface}`;
   }
 
   /** @override */
@@ -86,8 +86,8 @@ export class ApiInterface extends ApiItemContainerMixin(ApiNameMixin(ApiTypePara
   }
 
   /** @override */
-  public get canonicalReference(): string {
-    return ApiInterface.getCanonicalReference(this.name);
+  public get containerKey(): string {
+    return ApiInterface.getContainerKey(this.name);
   }
 
   /**

apps/api-extractor-model/src/model/ApiMethod.ts

@@ -48,11 +48,11 @@ export interface IApiMethodOptions extends
 export class ApiMethod extends ApiNameMixin(ApiTypeParameterListMixin(ApiParameterListMixin(
   ApiReleaseTagMixin(ApiReturnTypeMixin(ApiStaticMixin(ApiDeclaredItem)))))) {
 
-  public static getCanonicalReference(name: string, isStatic: boolean, overloadIndex: number): string {
+  public static getContainerKey(name: string, isStatic: boolean, overloadIndex: number): string {
     if (isStatic) {
-      return `(${name}:static,${overloadIndex})`;
+      return `${name}|${ApiItemKind.Method}|static|${overloadIndex}`;
     } else {
-      return `(${name}:instance,${overloadIndex})`;
+      return `${name}|${ApiItemKind.Method}|instance|${overloadIndex}`;
     }
   }
 
@@ -66,7 +66,7 @@ export class ApiMethod extends ApiNameMixin(ApiTypeParameterListMixin(ApiParamet
   }
 
   /** @override */
-  public get canonicalReference(): string {
-    return ApiMethod.getCanonicalReference(this.name, this.isStatic, this.overloadIndex);
+  public get containerKey(): string {
+    return ApiMethod.getContainerKey(this.name, this.isStatic, this.overloadIndex);
   }
 }

apps/api-extractor-model/src/model/ApiMethodSignature.ts

@@ -43,8 +43,8 @@ export interface IApiMethodSignatureOptions extends
 export class ApiMethodSignature extends ApiNameMixin(ApiTypeParameterListMixin(ApiParameterListMixin(
   ApiReleaseTagMixin(ApiReturnTypeMixin(ApiDeclaredItem))))) {
 
-  public static getCanonicalReference(name: string, overloadIndex: number): string {
-    return `(${name}:${overloadIndex})`;
+  public static getContainerKey(name: string, overloadIndex: number): string {
+    return `${name}|${ApiItemKind.MethodSignature}|${overloadIndex}`;
   }
 
   public constructor(options: IApiMethodSignatureOptions) {
@@ -57,7 +57,7 @@ export class ApiMethodSignature extends ApiNameMixin(ApiTypeParameterListMixin(A
   }
 
   /** @override */
-  public get canonicalReference(): string {
-    return ApiMethodSignature.getCanonicalReference(this.name, this.overloadIndex);
+  public get containerKey(): string {
+    return ApiMethodSignature.getContainerKey(this.name, this.overloadIndex);
   }
 }

apps/api-extractor-model/src/model/ApiModel.ts

@@ -71,7 +71,7 @@ export class ApiModel extends ApiItemContainerMixin(ApiItem) {
   }
 
   /** @override */
-  public get canonicalReference(): string {
+  public get containerKey(): string {
     return '';
   }