Skip to content

Commit a521679

Browse files
marshallstockmarshallstock
committed
[api-extractor] Added const case for isReadonly, use mixin on enum as well
1 parent 0261283 commit a521679

12 files changed

Lines changed: 113 additions & 32 deletions

File tree

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

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -998,15 +998,6 @@ export class MarkdownDocumenter {
998998
new DocPlainText({ configuration, text: ' ' })
999999
]);
10001000
}
1001-
//Should this be under modifer or descriptions?
1002-
if (ApiReadonlyMixin.isBaseClassOf(apiItem) && apiItem.isReadonly) {
1003-
section.appendNodesInParagraph([
1004-
new DocEmphasisSpan({ configuration, italic: true }, [
1005-
new DocPlainText({ configuration, text: '[Readonly]' })
1006-
]),
1007-
new DocPlainText({ configuration, text: ' ' })
1008-
]);
1009-
}
10101001

10111002
if (apiItem instanceof ApiDocumentedItem) {
10121003
if (apiItem.tsdocComment !== undefined) {
@@ -1028,6 +1019,12 @@ export class MarkdownDocumenter {
10281019
}
10291020
}
10301021

1022+
if (ApiReadonlyMixin.isBaseClassOf(apiItem)) {
1023+
if (apiItem.isReadonly) {
1024+
section.appendNodeInParagraph(new DocCodeSpan({ configuration, code: 'readonly' }));
1025+
}
1026+
}
1027+
10311028
return new DocTableCell({ configuration }, section.nodes);
10321029
}
10331030

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

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -471,8 +471,9 @@ export class ApiModelGenerator {
471471
const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
472472
const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
473473
const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
474+
const isReadonly: boolean = this._determineReadonly(astDeclaration);
474475

475-
apiEnum = new ApiEnum({ name, docComment, releaseTag, excerptTokens });
476+
apiEnum = new ApiEnum({ name, docComment, releaseTag, excerptTokens, isReadonly });
476477
parentApiItem.addMember(apiEnum);
477478
}
478479

@@ -669,18 +670,6 @@ export class ApiModelGenerator {
669670
this._processChildDeclarations(astDeclaration, exportedName, apiInterface);
670671
}
671672

672-
private _determineReadonly(astDeclaration: AstDeclaration): boolean {
673-
const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
674-
const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
675-
const declarationMetadata: DeclarationMetadata = this._collector.fetchDeclarationMetadata(astDeclaration);
676-
//Line 1: sees whether the readonly modifier is present
677-
//Line 2: sees if the TSDoc comment for @readonly is present
678-
//Line 3: sees whether a getter is present for a property with no setter
679-
return (astDeclaration.modifierFlags & ts.ModifierFlags.Readonly) !== 0
680-
|| (docComment !== undefined && docComment.modifierTagSet.hasTagName('@readonly'))
681-
|| (declarationMetadata.ancillaryDeclarations.length === 0 && astDeclaration.declaration.kind === ts.SyntaxKind.GetAccessor);
682-
}
683-
684673
private _processApiMethod(
685674
astDeclaration: AstDeclaration,
686675
exportedName: string | undefined,
@@ -1062,4 +1051,16 @@ export class ApiModelGenerator {
10621051
}
10631052
return parameters;
10641053
}
1054+
1055+
private _determineReadonly(astDeclaration: AstDeclaration): boolean {
1056+
const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
1057+
const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
1058+
const declarationMetadata: DeclarationMetadata = this._collector.fetchDeclarationMetadata(astDeclaration);
1059+
//Line 1: sees whether the readonly or const modifiers present
1060+
//Line 2: sees if the TSDoc comment for @readonly is present
1061+
//Line 3: sees whether a getter is present for a property with no setter
1062+
return (astDeclaration.modifierFlags & (ts.ModifierFlags.Readonly + ts.ModifierFlags.Const)) !== 0
1063+
|| (docComment !== undefined && docComment.modifierTagSet.hasTagName('@readonly'))
1064+
|| (declarationMetadata.ancillaryDeclarations.length === 0 && astDeclaration.declaration.kind === ts.SyntaxKind.GetAccessor);
1065+
}
10651066
}

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1070,7 +1070,8 @@
10701070
"endIndex": 2
10711071
}
10721072
}
1073-
]
1073+
],
1074+
"isReadonly": false
10741075
},
10751076
{
10761077
"kind": "Enum",
@@ -1127,7 +1128,8 @@
11271128
"endIndex": 2
11281129
}
11291130
}
1130-
]
1131+
],
1132+
"isReadonly": false
11311133
},
11321134
{
11331135
"kind": "Namespace",

‎build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,13 +29,13 @@ The constructor for this class is marked as internal. Third-party code should no
2929
| Property | Modifiers | Type | Description |
3030
| --- | --- | --- | --- |
3131
| [malformedEvent](./api-documenter-test.docclass1.malformedevent.md) | | [SystemEvent](./api-documenter-test.systemevent.md) | This event should have been marked as readonly. |
32-
| [modifiedEvent](./api-documenter-test.docclass1.modifiedevent.md) | | [SystemEvent](./api-documenter-test.systemevent.md) | <i>\[Readonly\]</i> This event is fired whenever the object is modified. |
32+
| [modifiedEvent](./api-documenter-test.docclass1.modifiedevent.md) | <code>readonly</code> | [SystemEvent](./api-documenter-test.systemevent.md) | This event is fired whenever the object is modified. |
3333
3434
## Properties
3535
3636
| Property | Modifiers | Type | Description |
3737
| --- | --- | --- | --- |
38-
| [readonlyProperty](./api-documenter-test.docclass1.readonlyproperty.md) | | string | <i>\[Readonly\]</i> |
38+
| [readonlyProperty](./api-documenter-test.docclass1.readonlyproperty.md) | <code>readonly</code> | string | |
3939
| [regularProperty](./api-documenter-test.docclass1.regularproperty.md) | | [SystemEvent](./api-documenter-test.systemevent.md) | This is a regular property that happens to use the SystemEvent type. |
4040
| [writeableProperty](./api-documenter-test.docclass1.writeableproperty.md) | | string | |
4141
| [writeonlyProperty](./api-documenter-test.docclass1.writeonlyproperty.md) | | string | API Extractor will surface an <code>ae-missing-getter</code> finding for this property. |

‎build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface7.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ export interface IDocInterface7
1717
| Property | Type | Description |
1818
| --- | --- | --- |
1919
| [optionalField?](./api-documenter-test.idocinterface7.optionalfield.md) | boolean | <i>(Optional)</i> Description of optionalField |
20-
| [optionalReadonlyField?](./api-documenter-test.idocinterface7.optionalreadonlyfield.md) | boolean | <i>(Optional)</i> <i>\[Readonly\]</i> Description of optionalReadonlyField |
20+
| [optionalReadonlyField?](./api-documenter-test.idocinterface7.optionalreadonlyfield.md) | boolean | <i>(Optional)</i> Description of optionalReadonlyField |
2121
| [optionalUndocumentedField?](./api-documenter-test.idocinterface7.optionalundocumentedfield.md) | boolean | <i>(Optional)</i> |
2222

2323
## Methods

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -394,7 +394,8 @@
394394
"endIndex": 2
395395
}
396396
}
397-
]
397+
],
398+
"isReadonly": true
398399
},
399400
{
400401
"kind": "Interface",
@@ -572,7 +573,8 @@
572573
"endIndex": 2
573574
}
574575
}
575-
]
576+
],
577+
"isReadonly": false
576578
},
577579
{
578580
"kind": "Class",

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

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,6 +213,64 @@
213213
],
214214
"extendsTokenRanges": []
215215
},
216+
{
217+
"kind": "Enum",
218+
"canonicalReference": "api-extractor-scenarios!ConstEnum:enum",
219+
"docComment": "/**\n * @public\n */\n",
220+
"excerptTokens": [
221+
{
222+
"kind": "Content",
223+
"text": "export declare const enum ConstEnum "
224+
}
225+
],
226+
"releaseTag": "Public",
227+
"name": "ConstEnum",
228+
"members": [
229+
{
230+
"kind": "EnumMember",
231+
"canonicalReference": "api-extractor-scenarios!ConstEnum.One:member",
232+
"docComment": "",
233+
"excerptTokens": [
234+
{
235+
"kind": "Content",
236+
"text": "One = "
237+
},
238+
{
239+
"kind": "Content",
240+
"text": "1"
241+
}
242+
],
243+
"releaseTag": "Public",
244+
"name": "One",
245+
"initializerTokenRange": {
246+
"startIndex": 1,
247+
"endIndex": 2
248+
}
249+
},
250+
{
251+
"kind": "EnumMember",
252+
"canonicalReference": "api-extractor-scenarios!ConstEnum.Zero:member",
253+
"docComment": "",
254+
"excerptTokens": [
255+
{
256+
"kind": "Content",
257+
"text": "Zero = "
258+
},
259+
{
260+
"kind": "Content",
261+
"text": "0"
262+
}
263+
],
264+
"releaseTag": "Public",
265+
"name": "Zero",
266+
"initializerTokenRange": {
267+
"startIndex": 1,
268+
"endIndex": 2
269+
}
270+
}
271+
],
272+
"isReadonly": true
273+
},
216274
{
217275
"kind": "Class",
218276
"canonicalReference": "api-extractor-scenarios!MyClass:class",

‎build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,14 @@
44
55
```ts
66

7+
// @public (undocumented)
8+
export const enum ConstEnum {
9+
// (undocumented)
10+
One = 1,
11+
// (undocumented)
12+
Zero = 0
13+
}
14+
715
// @public (undocumented)
816
export interface _IInternalThing {
917
// (undocumented)

‎build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/rollup.d.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
/** @public */
2+
export declare const enum ConstEnum {
3+
Zero = 0,
4+
One = 1
5+
}
6+
17
/** @public */
28
export declare interface _IInternalThing {
39
title: string;

‎build-tests/api-extractor-scenarios/src/readonlyDeclarations/index.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,11 @@ export interface _IInternalThing {
66
title: string;
77
}
88

9+
/** @public */
10+
export const enum ConstEnum {
11+
Zero,
12+
One = 1
13+
}
914
/** @public */
1015
export class MyClass {
1116
public get _writableThing(): _IInternalThing {

0 commit comments

Comments
 (0)