Skip to content

Commit 83dfeda

Browse files
octogonzoctogonz
authored
Merge pull request microsoft#1405 from microsoft/octogonz/ae-container-key
[api-extractor] Rename ApiItem.canonicalReference to ApiItem.containerKey
2 parents b9d4b6a + 4b81853 commit 83dfeda

55 files changed

Lines changed: 416 additions & 552 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎apps/api-documenter/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
"@microsoft/api-extractor-model": "7.2.0",
1919
"@microsoft/node-core-library": "3.13.0",
2020
"@microsoft/ts-command-line": "4.2.6",
21-
"@microsoft/tsdoc": "0.12.9",
21+
"@microsoft/tsdoc": "0.12.10",
2222
"colors": "~1.2.1",
2323
"js-yaml": "~3.13.1"
2424
},

‎apps/api-extractor-model/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
},
1919
"dependencies": {
2020
"@microsoft/node-core-library": "3.13.0",
21-
"@microsoft/tsdoc": "0.12.9",
21+
"@microsoft/tsdoc": "0.12.10",
2222
"@types/node": "8.5.8"
2323
},
2424
"devDependencies": {

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

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,6 @@ export interface IApiItemOptions {
4444

4545
export interface IApiItemJson {
4646
kind: ApiItemKind;
47-
canonicalReference: string;
4847
}
4948

5049
/**
@@ -85,17 +84,28 @@ export class ApiItem {
8584
/** @virtual */
8685
public serializeInto(jsonObject: Partial<IApiItemJson>): void {
8786
jsonObject.kind = this.kind;
88-
jsonObject.canonicalReference = this.canonicalReference;
8987
}
9088

91-
/** @virtual */
89+
/**
90+
* Identifies the subclass of the `ApiItem` base class.
91+
* @virtual
92+
*/
9293
public get kind(): ApiItemKind {
9394
throw new Error('ApiItem.kind was not implemented by the child class');
9495
}
9596

96-
/** @virtual */
97-
public get canonicalReference(): string {
98-
throw new Error('ApiItem.canonicalReference was not implemented by the child class');
97+
/**
98+
* Returns a string key that can be used to efficiently retrieve an `ApiItem` from an `ApiItemContainerMixin`.
99+
* The key is unique within the container. Its format is undocumented and may change at any time.
100+
*
101+
* @remarks
102+
* Use the `getContainerKey()` static member to construct the key. Each subclass has a different implementation
103+
* of this function, according to the aspects that are important for identifying it.
104+
*
105+
* @virtual
106+
*/
107+
public get containerKey(): string {
108+
throw new Error('ApiItem.containerKey was not implemented by the child class');
99109
}
100110

101111
/**
@@ -203,7 +213,7 @@ export class ApiItem {
203213

204214
/** @virtual */
205215
public getSortKey(): string {
206-
return this.canonicalReference;
216+
return this.containerKey;
207217
}
208218
}
209219

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

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ export interface IApiItemContainerJson extends IApiItemJson {
1919

2020
const _members: unique symbol = Symbol('ApiItemContainerMixin._members');
2121
const _membersSorted: unique symbol = Symbol('ApiItemContainerMixin._membersSorted');
22-
const _membersByCanonicalReference: unique symbol = Symbol('ApiItemContainerMixin._membersByCanonicalReference');
22+
const _membersByContainerKey: unique symbol = Symbol('ApiItemContainerMixin._membersByContainerKey');
2323
const _membersByName: unique symbol = Symbol('ApiItemContainerMixin._membersByName');
2424

2525
/**
@@ -58,9 +58,15 @@ export interface ApiItemContainerMixin extends ApiItem {
5858
addMember(member: ApiItem): void;
5959

6060
/**
61-
* Attempts to retrieve a member using its canonicalReference, or returns undefined if no matching member was found.
61+
* Attempts to retrieve a member using its containerKey, or returns `undefined` if no matching member was found.
62+
*
63+
* @remarks
64+
* Use the `getContainerKey()` static member to construct the key. Each subclass has a different implementation
65+
* of this function, according to the aspects that are important for identifying it.
66+
*
67+
* See {@link ApiItem.containerKey} for more information.
6268
*/
63-
tryGetMember(canonicalReference: string): ApiItem | undefined;
69+
tryGetMemberByKey(containerKey: string): ApiItem | undefined;
6470

6571
/**
6672
* Returns a list of members with the specified name.
@@ -85,7 +91,7 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(ba
8591
abstract class MixedClass extends baseClass implements ApiItemContainerMixin {
8692
public readonly [_members]: ApiItem[];
8793
public [_membersSorted]: boolean;
88-
public [_membersByCanonicalReference]: Map<string, ApiItem>;
94+
public [_membersByContainerKey]: Map<string, ApiItem>;
8995
public [_membersByName]: Map<string, ApiItem[]> | undefined;
9096

9197
/** @override */
@@ -106,7 +112,7 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(ba
106112
const options: IApiItemContainerMixinOptions = args[0] as IApiItemContainerMixinOptions;
107113

108114
this[_members] = [];
109-
this[_membersByCanonicalReference] = new Map<string, ApiItem>();
115+
this[_membersByContainerKey] = new Map<string, ApiItem>();
110116

111117
if (options.members) {
112118
for (const member of options.members) {
@@ -125,8 +131,8 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(ba
125131
}
126132

127133
public addMember(member: ApiItem): void {
128-
if (this[_membersByCanonicalReference].has(member.canonicalReference)) {
129-
throw new Error('Another member has already been added with the same name and canonicalReference');
134+
if (this[_membersByContainerKey].has(member.containerKey)) {
135+
throw new Error('Another member has already been added with the same name and containerKey');
130136
}
131137

132138
const existingParent: ApiItem | undefined = member[ApiItem_parent];
@@ -137,13 +143,13 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(ba
137143
this[_members].push(member);
138144
this[_membersByName] = undefined; // invalidate the lookup
139145
this[_membersSorted] = false;
140-
this[_membersByCanonicalReference].set(member.canonicalReference, member);
146+
this[_membersByContainerKey].set(member.containerKey, member);
141147

142148
member[ApiItem_parent] = this;
143149
}
144150

145-
public tryGetMember(canonicalReference: string): ApiItem | undefined {
146-
return this[_membersByCanonicalReference].get(canonicalReference);
151+
public tryGetMemberByKey(containerKey: string): ApiItem | undefined {
152+
return this[_membersByContainerKey].get(containerKey);
147153
}
148154

149155
public findMembersByName(name: string): ReadonlyArray<ApiItem> {

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,8 @@ export interface IApiCallSignatureOptions extends
5252
export class ApiCallSignature extends ApiTypeParameterListMixin(ApiParameterListMixin(ApiReleaseTagMixin(
5353
ApiReturnTypeMixin(ApiDeclaredItem)))) {
5454

55-
public static getCanonicalReference(overloadIndex: number): string {
56-
return `(:call,${overloadIndex})`;
55+
public static getContainerKey(overloadIndex: number): string {
56+
return `|${ApiItemKind.CallSignature}|${overloadIndex}`;
5757
}
5858

5959
public constructor(options: IApiCallSignatureOptions) {
@@ -66,7 +66,7 @@ export class ApiCallSignature extends ApiTypeParameterListMixin(ApiParameterList
6666
}
6767

6868
/** @override */
69-
public get canonicalReference(): string {
70-
return ApiCallSignature.getCanonicalReference(this.overloadIndex);
69+
public get containerKey(): string {
70+
return ApiCallSignature.getContainerKey(this.overloadIndex);
7171
}
7272
}

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -60,8 +60,8 @@ export class ApiClass extends ApiItemContainerMixin(ApiNameMixin(ApiTypeParamete
6060

6161
private readonly _implementsTypes: HeritageType[] = [];
6262

63-
public static getCanonicalReference(name: string): string {
64-
return `(${name}:class)`;
63+
public static getContainerKey(name: string): string {
64+
return `${name}|${ApiItemKind.Class}`;
6565
}
6666

6767
/** @override */
@@ -94,8 +94,8 @@ export class ApiClass extends ApiItemContainerMixin(ApiNameMixin(ApiTypeParamete
9494
}
9595

9696
/** @override */
97-
public get canonicalReference(): string {
98-
return ApiClass.getCanonicalReference(this.name);
97+
public get containerKey(): string {
98+
return ApiClass.getContainerKey(this.name);
9999
}
100100

101101
/**

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -65,8 +65,8 @@ export interface IApiConstructSignatureOptions extends
6565
export class ApiConstructSignature extends ApiTypeParameterListMixin(ApiParameterListMixin(ApiReleaseTagMixin(
6666
ApiReturnTypeMixin(ApiDeclaredItem)))) {
6767

68-
public static getCanonicalReference(overloadIndex: number): string {
69-
return `(:new,${overloadIndex})`;
68+
public static getContainerKey(overloadIndex: number): string {
69+
return `|${ApiItemKind.ConstructSignature}|${overloadIndex}`;
7070
}
7171

7272
public constructor(options: IApiConstructSignatureOptions) {
@@ -79,7 +79,7 @@ export class ApiConstructSignature extends ApiTypeParameterListMixin(ApiParamete
7979
}
8080

8181
/** @override */
82-
public get canonicalReference(): string {
83-
return ApiConstructSignature.getCanonicalReference(this.overloadIndex);
82+
public get containerKey(): string {
83+
return ApiConstructSignature.getContainerKey(this.overloadIndex);
8484
}
8585
}

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,8 @@ export interface IApiConstructorOptions extends
4545
*/
4646
export class ApiConstructor extends ApiParameterListMixin(ApiReleaseTagMixin(ApiDeclaredItem)) {
4747

48-
public static getCanonicalReference(overloadIndex: number): string {
49-
return `(:constructor,${overloadIndex})`;
48+
public static getContainerKey(overloadIndex: number): string {
49+
return `|${ApiItemKind.Constructor}|${overloadIndex}`;
5050
}
5151

5252
public constructor(options: IApiConstructorOptions) {
@@ -59,7 +59,7 @@ export class ApiConstructor extends ApiParameterListMixin(ApiReleaseTagMixin(Api
5959
}
6060

6161
/** @override */
62-
public get canonicalReference(): string {
63-
return ApiConstructor.getCanonicalReference(this.overloadIndex);
62+
public get containerKey(): string {
63+
return ApiConstructor.getContainerKey(this.overloadIndex);
6464
}
6565
}

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,8 @@ export class ApiEntryPoint extends ApiItemContainerMixin(ApiNameMixin(ApiItem))
4747
}
4848

4949
/** @override */
50-
public get canonicalReference(): string {
50+
public get containerKey(): string {
51+
// No prefix needed, because ApiEntryPoint is the only possible member of an ApiPackage
5152
return this.name;
5253
}
5354
}

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,8 @@ export interface IApiEnumOptions extends
4141
*/
4242
export class ApiEnum extends ApiItemContainerMixin(ApiNameMixin(ApiReleaseTagMixin(ApiDeclaredItem))) {
4343

44-
public static getCanonicalReference(name: string): string {
45-
return `(${name}:enum)`;
44+
public static getContainerKey(name: string): string {
45+
return `${name}|${ApiItemKind.Enum}`;
4646
}
4747

4848
public constructor(options: IApiEnumOptions) {
@@ -60,8 +60,8 @@ export class ApiEnum extends ApiItemContainerMixin(ApiNameMixin(ApiReleaseTagMix
6060
}
6161

6262
/** @override */
63-
public get canonicalReference(): string {
64-
return ApiEnum.getCanonicalReference(this.name);
63+
public get containerKey(): string {
64+
return ApiEnum.getContainerKey(this.name);
6565
}
6666

6767
/** @override */

0 commit comments

Comments
 (0)