Skip to content

Commit 8f53824

Browse files
octogonzoctogonz
authored
Merge pull request microsoft#3484 from zelliott/initializer
[api-extractor] Extract initializer information from relevant API items
2 parents 67963a1 + c878511 commit 8f53824

File tree

62 files changed

+460
-192
lines changed

Some content is hidden

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

62 files changed

+460
-192
lines changed

‎apps/api-documenter/src/documenters/MarkdownDocumenter.ts

Lines changed: 19 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,8 @@ import {
4040
IResolveDeclarationReferenceResult,
4141
ApiTypeAlias,
4242
ExcerptToken,
43-
ApiOptionalMixin
43+
ApiOptionalMixin,
44+
ApiInitializerMixin
4445
} from '@microsoft/api-extractor-model';
4546

4647
import { CustomDocNodes } from '../nodes/CustomDocNodeKind';
@@ -732,13 +733,7 @@ export class MarkdownDocumenter {
732733
new DocPlainText({ configuration, text: Utilities.getConciseSignature(apiEnumMember) })
733734
])
734735
]),
735-
736-
new DocTableCell({ configuration }, [
737-
new DocParagraph({ configuration }, [
738-
new DocCodeSpan({ configuration, code: apiEnumMember.initializerExcerpt.text })
739-
])
740-
]),
741-
736+
this._createInitializerCell(apiEnumMember),
742737
this._createDescriptionCell(apiEnumMember)
743738
])
744739
);
@@ -1033,6 +1028,22 @@ export class MarkdownDocumenter {
10331028
return new DocTableCell({ configuration }, section.nodes);
10341029
}
10351030

1031+
private _createInitializerCell(apiItem: ApiItem): DocTableCell {
1032+
const configuration: TSDocConfiguration = this._tsdocConfiguration;
1033+
1034+
const section: DocSection = new DocSection({ configuration });
1035+
1036+
if (ApiInitializerMixin.isBaseClassOf(apiItem)) {
1037+
if (apiItem.initializerExcerpt) {
1038+
section.appendNodeInParagraph(
1039+
new DocCodeSpan({ configuration, code: apiItem.initializerExcerpt.text })
1040+
);
1041+
}
1042+
}
1043+
1044+
return new DocTableCell({ configuration }, section.nodes);
1045+
}
1046+
10361047
private _writeBreadcrumb(output: DocSection, apiItem: ApiItem): void {
10371048
output.appendNodeInParagraph(
10381049
new DocLinkTag({

‎apps/api-documenter/src/documenters/YamlDocumenter.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -456,7 +456,7 @@ export class YamlDocumenter {
456456
yamlItem.type = 'field';
457457
const enumMember: ApiEnumMember = apiItem as ApiEnumMember;
458458

459-
if (enumMember.initializerExcerpt.text.length > 0) {
459+
if (enumMember.initializerExcerpt && enumMember.initializerExcerpt.text.length > 0) {
460460
yamlItem.numericValue = enumMember.initializerExcerpt.text;
461461
}
462462

‎apps/api-extractor/src/generators/ApiModelGenerator.ts

Lines changed: 25 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -502,8 +502,11 @@ export class ApiModelGenerator {
502502

503503
const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];
504504

505-
const initializerTokenRange: IExcerptTokenRange = ExcerptBuilder.createEmptyTokenRange();
506-
nodesToCapture.push({ node: enumMember.initializer, tokenRange: initializerTokenRange });
505+
let initializerTokenRange: IExcerptTokenRange | undefined = undefined;
506+
if (enumMember.initializer) {
507+
initializerTokenRange = ExcerptBuilder.createEmptyTokenRange();
508+
nodesToCapture.push({ node: enumMember.initializer, tokenRange: initializerTokenRange });
509+
}
507510

508511
const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
509512
const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
@@ -829,25 +832,29 @@ export class ApiModelGenerator {
829832
let apiProperty: ApiProperty | undefined = parentApiItem.tryGetMemberByKey(containerKey) as ApiProperty;
830833

831834
if (apiProperty === undefined) {
835+
const declaration: ts.Declaration = astDeclaration.declaration;
832836
const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];
833837

834838
const propertyTypeTokenRange: IExcerptTokenRange = ExcerptBuilder.createEmptyTokenRange();
835839
let propertyTypeNode: ts.TypeNode | undefined;
836840

837-
if (
838-
ts.isPropertyDeclaration(astDeclaration.declaration) ||
839-
ts.isGetAccessorDeclaration(astDeclaration.declaration)
840-
) {
841-
propertyTypeNode = astDeclaration.declaration.type;
841+
if (ts.isPropertyDeclaration(declaration) || ts.isGetAccessorDeclaration(declaration)) {
842+
propertyTypeNode = declaration.type;
842843
}
843844

844-
if (ts.isSetAccessorDeclaration(astDeclaration.declaration)) {
845+
if (ts.isSetAccessorDeclaration(declaration)) {
845846
// Note that TypeScript always reports an error if a setter does not have exactly one parameter.
846-
propertyTypeNode = astDeclaration.declaration.parameters[0].type;
847+
propertyTypeNode = declaration.parameters[0].type;
847848
}
848849

849850
nodesToCapture.push({ node: propertyTypeNode, tokenRange: propertyTypeTokenRange });
850851

852+
let initializerTokenRange: IExcerptTokenRange | undefined = undefined;
853+
if (ts.isPropertyDeclaration(declaration) && declaration.initializer) {
854+
initializerTokenRange = ExcerptBuilder.createEmptyTokenRange();
855+
nodesToCapture.push({ node: declaration.initializer, tokenRange: initializerTokenRange });
856+
}
857+
851858
const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
852859
const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
853860
const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
@@ -866,7 +873,8 @@ export class ApiModelGenerator {
866873
isOptional,
867874
isReadonly,
868875
excerptTokens,
869-
propertyTypeTokenRange
876+
propertyTypeTokenRange,
877+
initializerTokenRange
870878
});
871879
parentApiItem.addMember(apiProperty);
872880
} else {
@@ -985,6 +993,12 @@ export class ApiModelGenerator {
985993
const variableTypeTokenRange: IExcerptTokenRange = ExcerptBuilder.createEmptyTokenRange();
986994
nodesToCapture.push({ node: variableDeclaration.type, tokenRange: variableTypeTokenRange });
987995

996+
let initializerTokenRange: IExcerptTokenRange | undefined = undefined;
997+
if (variableDeclaration.initializer) {
998+
initializerTokenRange = ExcerptBuilder.createEmptyTokenRange();
999+
nodesToCapture.push({ node: variableDeclaration.initializer, tokenRange: initializerTokenRange });
1000+
}
1001+
9881002
const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
9891003
const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
9901004
const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
@@ -997,6 +1011,7 @@ export class ApiModelGenerator {
9971011
releaseTag,
9981012
excerptTokens,
9991013
variableTypeTokenRange,
1014+
initializerTokenRange,
10001015
isReadonly
10011016
});
10021017

‎build-tests/api-documenter-test/etc/api-documenter-test.api.json

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"metadata": {
33
"toolPackage": "@microsoft/api-extractor",
44
"toolVersion": "[test mode]",
5-
"schemaVersion": 1007,
5+
"schemaVersion": 1008,
66
"oldestForwardsCompatibleVersion": 1001,
77
"tsdocConfig": {
88
"$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
@@ -1070,12 +1070,12 @@
10701070
"text": "1"
10711071
}
10721072
],
1073-
"releaseTag": "Public",
1074-
"name": "One",
10751073
"initializerTokenRange": {
10761074
"startIndex": 1,
10771075
"endIndex": 2
1078-
}
1076+
},
1077+
"releaseTag": "Public",
1078+
"name": "One"
10791079
},
10801080
{
10811081
"kind": "EnumMember",
@@ -1091,12 +1091,12 @@
10911091
"text": "2"
10921092
}
10931093
],
1094-
"releaseTag": "Public",
1095-
"name": "Two",
10961094
"initializerTokenRange": {
10971095
"startIndex": 1,
10981096
"endIndex": 2
1099-
}
1097+
},
1098+
"releaseTag": "Public",
1099+
"name": "Two"
11001100
},
11011101
{
11021102
"kind": "EnumMember",
@@ -1112,12 +1112,12 @@
11121112
"text": "0"
11131113
}
11141114
],
1115-
"releaseTag": "Public",
1116-
"name": "Zero",
11171115
"initializerTokenRange": {
11181116
"startIndex": 1,
11191117
"endIndex": 2
1120-
}
1118+
},
1119+
"releaseTag": "Public",
1120+
"name": "Zero"
11211121
}
11221122
]
11231123
},
@@ -1149,12 +1149,12 @@
11491149
"text": "0"
11501150
}
11511151
],
1152-
"releaseTag": "Public",
1153-
"name": "Left",
11541152
"initializerTokenRange": {
11551153
"startIndex": 1,
11561154
"endIndex": 2
1157-
}
1155+
},
1156+
"releaseTag": "Public",
1157+
"name": "Left"
11581158
},
11591159
{
11601160
"kind": "EnumMember",
@@ -1170,12 +1170,12 @@
11701170
"text": "1"
11711171
}
11721172
],
1173-
"releaseTag": "Public",
1174-
"name": "Right",
11751173
"initializerTokenRange": {
11761174
"startIndex": 1,
11771175
"endIndex": 2
1178-
}
1176+
},
1177+
"releaseTag": "Public",
1178+
"name": "Right"
11791179
}
11801180
]
11811181
},

‎build-tests/api-extractor-scenarios/etc/test-outputs/ambientNameConflict/api-extractor-scenarios.api.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"metadata": {
33
"toolPackage": "@microsoft/api-extractor",
44
"toolVersion": "[test mode]",
5-
"schemaVersion": 1007,
5+
"schemaVersion": 1008,
66
"oldestForwardsCompatibleVersion": 1001,
77
"tsdocConfig": {
88
"$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",

‎build-tests/api-extractor-scenarios/etc/test-outputs/ambientNameConflict2/api-extractor-scenarios.api.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"metadata": {
33
"toolPackage": "@microsoft/api-extractor",
44
"toolVersion": "[test mode]",
5-
"schemaVersion": 1007,
5+
"schemaVersion": 1008,
66
"oldestForwardsCompatibleVersion": 1001,
77
"tsdocConfig": {
88
"$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",

‎build-tests/api-extractor-scenarios/etc/test-outputs/ancillaryDeclarations/api-extractor-scenarios.api.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"metadata": {
33
"toolPackage": "@microsoft/api-extractor",
44
"toolVersion": "[test mode]",
5-
"schemaVersion": 1007,
5+
"schemaVersion": 1008,
66
"oldestForwardsCompatibleVersion": 1001,
77
"tsdocConfig": {
88
"$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",

0 commit comments

Comments
 (0)