Skip to content

Commit ac340ea

Browse files
dgaetadgaeta
committed
Added ApiFileJson class to abstract the difference between ApiItemKind and the string we write to API JSON files
1 parent a6e0b92 commit ac340ea

File tree

3 files changed

+92
-26
lines changed

3 files changed

+92
-26
lines changed

‎api-extractor/src/ResolvedApiItem.ts‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import ApiItemContainer from './definitions/ApiItemContainer';
33
import { ApiTag } from './definitions/ApiDocumentation';
44
import { IDocElement, IParam } from './IDocElement';
55
import { IDocItem } from './IDocItem';
6+
import ApiJsonFile from './generators/ApiJsonFile';
67

78
/**
89
* A class to abstract away the difference between an item from our public API that could be
@@ -55,26 +56,26 @@ export default class ResolvedApiItem {
5556
let returnsMessage: IDocElement[] = undefined;
5657
let members: { [name: string]: IDocItem} = undefined;
5758
switch (docItem.kind) {
58-
case 'IDocFunction':
59+
case 'function':
5960
parameters = docItem.parameters;
6061
returnsMessage = docItem.returnValue.description;
6162
break;
62-
case 'IDocMethod':
63+
case 'method':
6364
parameters = docItem.parameters;
6465
returnsMessage = docItem.returnValue.description;
6566
break;
66-
case 'IDocClass':
67+
case 'class':
6768
members = docItem.members;
6869
break;
69-
case 'IDocPackage':
70-
members = docItem.exports;
70+
case 'interface':
71+
members = docItem.members;
7172
break;
7273
default:
7374
break;
7475
}
7576

7677
return new ResolvedApiItem(
77-
ApiItemKind[docItem.kind],
78+
ApiJsonFile.convertJsonToKind(docItem.kind),
7879
docItem.summary,
7980
docItem.remarks,
8081
docItem.deprecatedMessage,

‎api-extractor/src/generators/ApiJsonFile.ts‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
import { ApiItemKind } from '../definitions/ApiItem';
2+
3+
/**
4+
* Supports the conversion between ApiItems that are loaded from ApiItem to JSON notation
5+
* and vice versa.
6+
*/
7+
export default class ApiJsonFile {
8+
private static _KIND_CONSTRUCTOR: string = 'constructor';
9+
private static _KIND_CLASS: string = 'class';
10+
private static _KIND_ENUM: string = 'enum';
11+
private static _KIND_INTERFACE: string = 'interface';
12+
private static _KIND_FUNCTION: string = 'function';
13+
private static _KIND_PACKAGE: string = 'package';
14+
private static _KIND_PROPERTY: string = 'property';
15+
private static _KIND_METHOD: string = 'method';
16+
17+
/**
18+
* Uses the lowercase string that represents 'kind' in an API JSON file, and
19+
* converts it to an ApiItemKind enum value.
20+
*/
21+
public static convertJsonToKind(jsonItemKind: string): ApiItemKind {
22+
switch (jsonItemKind) {
23+
case (this._KIND_CONSTRUCTOR):
24+
return ApiItemKind.Constructor;
25+
case (this._KIND_CLASS):
26+
return ApiItemKind.Class;
27+
case (this._KIND_ENUM):
28+
return ApiItemKind.Enum;
29+
case (this._KIND_INTERFACE):
30+
return ApiItemKind.Interface;
31+
case (this._KIND_FUNCTION):
32+
return ApiItemKind.Function;
33+
case (this._KIND_PACKAGE):
34+
return ApiItemKind.Package;
35+
case (this._KIND_PROPERTY):
36+
return ApiItemKind.Property;
37+
case (this._KIND_METHOD):
38+
return ApiItemKind.Method;
39+
default:
40+
new Error('Unsupported kind when converting JSON item kind to API item kind.');
41+
break;
42+
}
43+
}
44+
45+
/**
46+
* Converts the an ApiItemKind into a lower-case string that is written to API JSON files.
47+
*/
48+
public static convertKindToJson(apiItemKind: ApiItemKind): string {
49+
switch (apiItemKind) {
50+
case (ApiItemKind.Constructor):
51+
return this._KIND_CONSTRUCTOR;
52+
case (ApiItemKind.Class):
53+
return this._KIND_CLASS;
54+
case (ApiItemKind.Enum):
55+
return this._KIND_ENUM;
56+
case (ApiItemKind.Interface):
57+
return this._KIND_INTERFACE;
58+
case (ApiItemKind.Function):
59+
return this._KIND_FUNCTION;
60+
case (ApiItemKind.Package):
61+
return this._KIND_PACKAGE;
62+
case (ApiItemKind.Property):
63+
return this._KIND_PROPERTY;
64+
case (ApiItemKind.Method):
65+
return this._KIND_METHOD;
66+
default:
67+
new Error('Unsupported API item kind when converting to string used in API JSON file.');
68+
break;
69+
}
70+
}
71+
}

‎api-extractor/src/generators/ApiJsonGenerator.ts‎

Lines changed: 14 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ import ApiMethod from '../definitions/ApiMethod';
1717
import { ApiTag } from '../definitions/ApiDocumentation';
1818
import { IReturn, IParam }from '../IDocElement';
1919
import JsonFile from '../JsonFile';
20+
import ApiJsonFile from './ApiJsonFile';
2021

2122
/**
2223
* For a library such as "example-package", ApiFileGenerator generates the "example-package.api.ts"
@@ -29,15 +30,6 @@ import JsonFile from '../JsonFile';
2930
*/
3031
export default class ApiJsonGenerator extends ApiItemVisitor {
3132
private static _methodCounter: number = 0;
32-
33-
private static _KIND_CONSTRUCTOR: string = 'constructor';
34-
private static _KIND_CLASS: string = 'class';
35-
private static _KIND_ENUM: string = 'enum';
36-
private static _KIND_INTERFACE: string = 'interface';
37-
private static _KIND_FUNCTION: string = 'function';
38-
private static _KIND_PACKAGE: string = 'package';
39-
private static _KIND_PROPERTY: string = 'property';
40-
private static _KIND_METHOD: string = 'method';
4133
private static _MEMBERS_KEY: string = 'members';
4234
private static _EXPORTS_KEY: string = 'exports';
4335

@@ -74,9 +66,9 @@ export default class ApiJsonGenerator extends ApiItemVisitor {
7466

7567
protected visitApiStructuredType(apiStructuredType: ApiStructuredType, refObject?: Object): void {
7668
const kind: string =
77-
apiStructuredType.kind === ApiItemKind.Class ? ApiJsonGenerator._KIND_CLASS :
78-
apiStructuredType.kind === ApiItemKind.Interface ? ApiJsonGenerator._KIND_INTERFACE :
79-
'';
69+
apiStructuredType.kind === ApiItemKind.Class ? ApiJsonFile.convertKindToJson(ApiItemKind.Class) :
70+
apiStructuredType.kind === ApiItemKind.Interface ?
71+
ApiJsonFile.convertKindToJson(ApiItemKind.Interface) : '';
8072

8173
const structureNode: Object = {
8274
kind: kind,
@@ -107,7 +99,7 @@ export default class ApiJsonGenerator extends ApiItemVisitor {
10799
protected visitApiEnum(apiEnum: ApiEnum, refObject?: Object): void {
108100
const valuesNode: Object = {};
109101
const enumNode: Object = {
110-
kind: ApiJsonGenerator._KIND_ENUM,
102+
kind: ApiJsonFile.convertKindToJson(apiEnum.kind),
111103
values: valuesNode,
112104
deprecatedMessage: apiEnum.documentation.deprecatedMessage || [],
113105
summary: apiEnum.documentation.summary || [],
@@ -147,7 +139,7 @@ export default class ApiJsonGenerator extends ApiItemVisitor {
147139
};
148140

149141
const newNode: Object = {
150-
kind: ApiJsonGenerator._KIND_FUNCTION,
142+
kind: ApiJsonFile.convertKindToJson(apiFunction.kind),
151143
returnValue: returnValueNode,
152144
parameters: apiFunction.documentation.parameters,
153145
deprecatedMessage: apiFunction.documentation.deprecatedMessage || [],
@@ -160,9 +152,11 @@ export default class ApiJsonGenerator extends ApiItemVisitor {
160152
}
161153

162154
protected visitApiPackage(apiPackage: ApiPackage, refObject?: Object): void {
163-
refObject['kind'] = ApiJsonGenerator._KIND_PACKAGE; /* tslint:disable-line:no-string-literal */
164-
refObject['summary'] = apiPackage.documentation.summary; /* tslint:disable-line:no-string-literal */
165-
refObject['remarks'] = apiPackage.documentation.remarks; /* tslint:disable-line:no-string-literal */
155+
/* tslint:disable:no-string-literal */
156+
refObject['kind'] = ApiJsonFile.convertKindToJson(apiPackage.kind);
157+
refObject['summary'] = apiPackage.documentation.summary;
158+
refObject['remarks'] = apiPackage.documentation.remarks;
159+
/* tslint:enable:no-string-literal */
166160

167161
const membersNode: Object = {};
168162
refObject[ApiJsonGenerator._EXPORTS_KEY] = membersNode;
@@ -182,7 +176,7 @@ export default class ApiJsonGenerator extends ApiItemVisitor {
182176
}
183177

184178
const newNode: Object = {
185-
kind: ApiJsonGenerator._KIND_PROPERTY,
179+
kind: ApiJsonFile.convertKindToJson(apiProperty.kind),
186180
isOptional: !!apiProperty.isOptional,
187181
isReadOnly: !!apiProperty.isReadOnly,
188182
isStatic: !!apiProperty.isStatic,
@@ -204,7 +198,7 @@ export default class ApiJsonGenerator extends ApiItemVisitor {
204198
let newNode: Object;
205199
if (apiMethod.name === '__constructor') {
206200
newNode = {
207-
kind: ApiJsonGenerator._KIND_CONSTRUCTOR,
201+
kind: ApiJsonFile.convertKindToJson(ApiItemKind.Constructor),
208202
signature: apiMethod.getDeclarationLine(),
209203
parameters: apiMethod.documentation.parameters,
210204
deprecatedMessage: apiMethod.documentation.deprecatedMessage || [],
@@ -218,7 +212,7 @@ export default class ApiJsonGenerator extends ApiItemVisitor {
218212
};
219213

220214
newNode = {
221-
kind: ApiJsonGenerator._KIND_METHOD,
215+
kind: ApiJsonFile.convertKindToJson(apiMethod.kind),
222216
signature: apiMethod.getDeclarationLine(),
223217
accessModifier: apiMethod.accessModifier ? AccessModifier[apiMethod.accessModifier].toLowerCase() : '',
224218
isOptional: !!apiMethod.isOptional,

0 commit comments

Comments
 (0)