Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[api-documenter/-extractor/-model] Support 'abstract' Modifier #3662

Merged
merged 13 commits into from
Jan 25, 2023
Merged

[api-documenter/-extractor/-model] Support 'abstract' Modifier #3662

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
43f80c4
[api-extractor-model, api-extractor] Support for 'abstract' modifier
fwienber Sep 29, 2022
b146047
[api-documenter] Add 'abstract' to "Modifiers" column
fwienber Sep 29, 2022
66932f6
[api-documenter] Separate "Abstract Classes" overview table
fwienber Sep 29, 2022
c4c0d53
[api-extractor-model, api-extractor] Support for 'abstract' modifier …
fwienber Oct 18, 2022
2c272dc
Merge remote-tracking branch 'origin/main' into fwienber/support-abst…
fwienber Oct 18, 2022
2088fd3
Add new ApiJsonSchemaVersion (V_1011) for 'isAbstract' field
fwienber Oct 18, 2022
dc41cb5
Add change log entries for new 'isAbstract' field
fwienber Oct 18, 2022
5a7e4db
[api-documenter] Change modifier output order to match TypeScript syntax
fwienber Oct 18, 2022
c1e886a
Regenerate expected test data after updating schemaVersion
fwienber Oct 18, 2022
0a55655
[api-documenter] Add test for an abstract class with abstract method …
fwienber Nov 29, 2022
73cd30e
Merge remote-tracking branch 'remotes/origin/main' into fwienber/supp…
octogonz Jan 25, 2023
06c94ac
Update change logs
octogonz Jan 25, 2023
c61ad43
rush build
octogonz Jan 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 24 additions & 1 deletion apps/api-documenter/src/documenters/MarkdownDocumenter.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ import {
ApiPropertyItem,
ApiInterface,
Excerpt,
ApiAbstractMixin,
ApiParameterListMixin,
ApiReturnTypeMixin,
ApiDeclaredItem,
Expand Down Expand Up @@ -502,6 +503,11 @@ export class MarkdownDocumenter {
private _writePackageOrNamespaceTables(output: DocSection, apiContainer: ApiPackage | ApiNamespace): void {
const configuration: TSDocConfiguration = this._tsdocConfiguration;

const abstractClassesTable: DocTable = new DocTable({
configuration,
headerTitles: ['Abstract Class', 'Description']
});
fwienber marked this conversation as resolved.
Show resolved Hide resolved

const classesTable: DocTable = new DocTable({
configuration,
headerTitles: ['Class', 'Description']
Expand Down Expand Up @@ -550,7 +556,11 @@ export class MarkdownDocumenter {

switch (apiMember.kind) {
case ApiItemKind.Class:
classesTable.addRow(row);
if (ApiAbstractMixin.isBaseClassOf(apiMember) && apiMember.isAbstract) {
abstractClassesTable.addRow(row);
} else {
classesTable.addRow(row);
}
this._writeApiItemPage(apiMember);
break;

Expand Down Expand Up @@ -591,6 +601,11 @@ export class MarkdownDocumenter {
output.appendNode(classesTable);
}

if (abstractClassesTable.rows.length > 0) {
output.appendNode(new DocHeading({ configuration, title: 'Abstract Classes' }));
output.appendNode(abstractClassesTable);
}

if (enumerationsTable.rows.length > 0) {
output.appendNode(new DocHeading({ configuration, title: 'Enumerations' }));
output.appendNode(enumerationsTable);
Expand Down Expand Up @@ -1057,6 +1072,14 @@ export class MarkdownDocumenter {
}
}

if (ApiAbstractMixin.isBaseClassOf(apiItem)) {
if (apiItem.isAbstract) {
section.appendNode(
new DocParagraph({ configuration }, [new DocCodeSpan({ configuration, code: 'abstract' })])
);
}
}
fwienber marked this conversation as resolved.
Show resolved Hide resolved

return new DocTableCell({ configuration }, section.nodes);
}

Expand Down
5 changes: 5 additions & 0 deletions apps/api-extractor/src/generators/ApiModelGenerator.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -385,9 +385,12 @@ export class ApiModelGenerator {
const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
const isAbstract: boolean =
(ts.getCombinedModifierFlags(classDeclaration) & ts.ModifierFlags.Abstract) !== 0;

apiClass = new ApiClass({
name,
isAbstract,
docComment,
releaseTag,
excerptTokens,
Expand Down Expand Up @@ -705,9 +708,11 @@ export class ApiModelGenerator {
const isOptional: boolean =
(astDeclaration.astSymbol.followedSymbol.flags & ts.SymbolFlags.Optional) !== 0;
const isProtected: boolean = (astDeclaration.modifierFlags & ts.ModifierFlags.Protected) !== 0;
const isAbstract: boolean = (astDeclaration.modifierFlags & ts.ModifierFlags.Abstract) !== 0;

apiMethod = new ApiMethod({
name,
isAbstract,
docComment,
releaseTag,
isProtected,
Expand Down
12 changes: 12 additions & 0 deletions build-tests/api-documenter-scenarios/etc/inheritedMembers/api-documenter-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,7 @@
}
],
"releaseTag": "Public",
"isAbstract": false,
"name": "Class1",
"preserveMemberOrder": false,
"members": [
Expand Down Expand Up @@ -302,6 +303,7 @@
}
],
"isOptional": false,
"isAbstract": false,
"name": "someOverload"
}
],
Expand Down Expand Up @@ -344,6 +346,7 @@
}
}
],
"isAbstract": false,
"name": "Class2",
"preserveMemberOrder": false,
"members": [
Expand Down Expand Up @@ -421,6 +424,7 @@
}
],
"isOptional": false,
"isAbstract": false,
"name": "someMethod"
},
{
Expand Down Expand Up @@ -501,6 +505,7 @@
}
],
"releaseTag": "Public",
"isAbstract": false,
"name": "ExtendsAnonymousClass",
"preserveMemberOrder": false,
"members": [],
Expand Down Expand Up @@ -530,6 +535,7 @@
}
],
"releaseTag": "Public",
"isAbstract": false,
"name": "ExtendsClassFromAnotherPackage",
"preserveMemberOrder": false,
"members": [],
Expand Down Expand Up @@ -559,6 +565,7 @@
}
],
"releaseTag": "Public",
"isAbstract": false,
"name": "ExtendsClassLikeVariable",
"preserveMemberOrder": false,
"members": [],
Expand Down Expand Up @@ -588,6 +595,7 @@
}
],
"releaseTag": "Public",
"isAbstract": false,
"name": "ExtendsUnexportedClass",
"preserveMemberOrder": false,
"members": [],
Expand Down Expand Up @@ -903,6 +911,7 @@
}
],
"releaseTag": "Public",
"isAbstract": false,
"name": "Class3",
"preserveMemberOrder": false,
"members": [
Expand Down Expand Up @@ -951,6 +960,7 @@
}
],
"isOptional": false,
"isAbstract": false,
"name": "someMethod"
},
{
Expand Down Expand Up @@ -998,6 +1008,7 @@
}
],
"isOptional": false,
"isAbstract": false,
"name": "someOverload"
},
{
Expand Down Expand Up @@ -1045,6 +1056,7 @@
}
],
"isOptional": false,
"isAbstract": false,
"name": "someOverload"
},
{
Expand Down
15 changes: 15 additions & 0 deletions build-tests/api-documenter-test/etc/api-documenter-test.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,6 +231,7 @@
}
],
"releaseTag": "Public",
"isAbstract": false,
"name": "DecoratorExample",
"preserveMemberOrder": false,
"members": [
Expand Down Expand Up @@ -294,6 +295,7 @@
}
],
"releaseTag": "Public",
"isAbstract": false,
"name": "DocBaseClass",
"preserveMemberOrder": false,
"members": [
Expand Down Expand Up @@ -385,6 +387,7 @@
}
],
"releaseTag": "Public",
"isAbstract": false,
"name": "DocClass1",
"preserveMemberOrder": false,
"members": [
Expand Down Expand Up @@ -416,6 +419,7 @@
"overloadIndex": 1,
"parameters": [],
"isOptional": false,
"isAbstract": false,
"name": "deprecatedExample"
},
{
Expand Down Expand Up @@ -479,6 +483,7 @@
}
],
"isOptional": false,
"isAbstract": false,
"name": "exampleFunction"
},
{
Expand Down Expand Up @@ -526,6 +531,7 @@
}
],
"isOptional": false,
"isAbstract": false,
"name": "exampleFunction"
},
{
Expand Down Expand Up @@ -604,6 +610,7 @@
}
],
"isOptional": false,
"isAbstract": false,
"name": "genericWithConstraintAndDefault"
},
{
Expand Down Expand Up @@ -634,6 +641,7 @@
"overloadIndex": 1,
"parameters": [],
"isOptional": false,
"isAbstract": false,
"name": "interestingEdgeCases"
},
{
Expand Down Expand Up @@ -770,6 +778,7 @@
}
],
"isOptional": false,
"isAbstract": false,
"name": "optionalParamFunction"
},
{
Expand Down Expand Up @@ -921,6 +930,7 @@
}
],
"isOptional": false,
"isAbstract": false,
"name": "sumWithExample"
},
{
Expand Down Expand Up @@ -951,6 +961,7 @@
"overloadIndex": 1,
"parameters": [],
"isOptional": false,
"isAbstract": false,
"name": "tableExample"
},
{
Expand Down Expand Up @@ -1038,6 +1049,7 @@
}
],
"releaseTag": "Public",
"isAbstract": false,
"name": "DocClassInterfaceMerge",
"preserveMemberOrder": false,
"members": [],
Expand Down Expand Up @@ -1463,6 +1475,7 @@
}
}
],
"isAbstract": false,
"name": "Generic",
"preserveMemberOrder": false,
"members": [],
Expand Down Expand Up @@ -2534,6 +2547,7 @@
}
],
"releaseTag": "Public",
"isAbstract": false,
"name": "SystemEvent",
"preserveMemberOrder": false,
"members": [
Expand Down Expand Up @@ -2582,6 +2596,7 @@
}
],
"isOptional": false,
"isAbstract": false,
"name": "addHandler"
}
],
Expand Down
1 change: 1 addition & 0 deletions ...d-tests/api-extractor-scenarios/etc/ambientNameConflict2/api-extractor-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,7 @@
}
],
"releaseTag": "Public",
"isAbstract": false,
"name": "Date_2",
"preserveMemberOrder": false,
"members": [],
Expand Down
1 change: 1 addition & 0 deletions ...-tests/api-extractor-scenarios/etc/ancillaryDeclarations/api-extractor-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,7 @@
}
],
"releaseTag": "Public",
"isAbstract": false,
"name": "MyClass",
"preserveMemberOrder": false,
"members": [],
Expand Down
Loading