From b93f5493f84af3a3d3a7577612e7bd53ffd5e67d Mon Sep 17 00:00:00 2001 From: mrshllstock Date: Thu, 19 May 2022 13:42:03 -0700 Subject: [PATCH 01/14] [api-extractor] Add readonlymixin --- .../src/documenters/MarkdownDocumenter.ts | 12 +- .../src/generators/ApiModelGenerator.ts | 27 +- .../etc/api-documenter-test.api.json | 47 +++ .../markdown/api-documenter-test.docclass1.md | 4 +- .../api-documenter-test.idocinterface7.md | 2 +- .../config/build-config.json | 1 + .../api-extractor-scenarios.api.json | 9 + .../api-extractor-scenarios.api.json | 2 + .../api-extractor-scenarios.api.json | 3 + .../api-extractor-scenarios.api.json | 3 + .../api-extractor-scenarios.api.json | 1 + .../api-extractor-scenarios.api.json | 6 + .../api-extractor-scenarios.api.json | 3 + .../api-extractor-scenarios.api.json | 5 + .../api-extractor-scenarios.api.json | 3 + .../api-extractor-scenarios.api.json | 2 + .../api-extractor-scenarios.api.json | 1 + .../api-extractor-scenarios.api.json | 2 + .../api-extractor-scenarios.api.json | 2 + .../api-extractor-scenarios.api.json | 3 + .../api-extractor-scenarios.api.json | 2 + .../api-extractor-scenarios.api.json | 3 + .../api-extractor-scenarios.api.json | 4 + .../api-extractor-scenarios.api.json | 365 ++++++++++++++++++ .../api-extractor-scenarios.api.md | 27 ++ .../readonlyDeclarations/rollup.d.ts | 19 + .../api-extractor-scenarios.api.json | 4 + .../api-extractor-scenarios.api.json | 4 + .../src/readonlyDeclarations/index.ts | 28 ++ .../workspace/common/pnpm-lock.yaml | 14 +- .../api-readonly-mixin_2022-05-19-20-18.json | 10 + .../api-readonly-mixin_2022-05-19-20-18.json | 10 + .../api-readonly-mixin_2022-05-19-20-18.json | 10 + common/reviews/api/api-extractor-model.api.md | 32 +- libraries/api-extractor-model/src/index.ts | 1 + .../src/items/ApiPropertyItem.ts | 6 +- .../src/mixins/ApiReadonlyMixin.ts | 110 ++++++ .../src/model/ApiInterface.ts | 6 +- .../src/model/ApiMethod.ts | 6 +- .../src/model/ApiMethodSignature.ts | 6 +- .../src/model/ApiProperty.ts | 5 +- 41 files changed, 783 insertions(+), 27 deletions(-) create mode 100644 build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json create mode 100644 build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.md create mode 100644 build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/rollup.d.ts create mode 100644 build-tests/api-extractor-scenarios/src/readonlyDeclarations/index.ts create mode 100644 common/changes/@microsoft/api-documenter/api-readonly-mixin_2022-05-19-20-18.json create mode 100644 common/changes/@microsoft/api-extractor-model/api-readonly-mixin_2022-05-19-20-18.json create mode 100644 common/changes/@microsoft/api-extractor/api-readonly-mixin_2022-05-19-20-18.json create mode 100644 libraries/api-extractor-model/src/mixins/ApiReadonlyMixin.ts diff --git a/apps/api-documenter/src/documenters/MarkdownDocumenter.ts b/apps/api-documenter/src/documenters/MarkdownDocumenter.ts index 8fbf10db3a5..9b569a28281 100644 --- a/apps/api-documenter/src/documenters/MarkdownDocumenter.ts +++ b/apps/api-documenter/src/documenters/MarkdownDocumenter.ts @@ -40,7 +40,8 @@ import { IResolveDeclarationReferenceResult, ApiTypeAlias, ExcerptToken, - ApiOptionalMixin + ApiOptionalMixin, + ApiReadonlyMixin } from '@microsoft/api-extractor-model'; import { CustomDocNodes } from '../nodes/CustomDocNodeKind'; @@ -997,6 +998,15 @@ export class MarkdownDocumenter { new DocPlainText({ configuration, text: ' ' }) ]); } + //Should this be under modifer or descriptions? + if (ApiReadonlyMixin.isBaseClassOf(apiItem) && apiItem.isReadonly) { + section.appendNodesInParagraph([ + new DocEmphasisSpan({ configuration, italic: true }, [ + new DocPlainText({ configuration, text: '[Readonly]' }) + ]), + new DocPlainText({ configuration, text: ' ' }) + ]); + } if (apiItem instanceof ApiDocumentedItem) { if (apiItem.tsdocComment !== undefined) { diff --git a/apps/api-extractor/src/generators/ApiModelGenerator.ts b/apps/api-extractor/src/generators/ApiModelGenerator.ts index cb0d52e17d3..1119ae7c41c 100644 --- a/apps/api-extractor/src/generators/ApiModelGenerator.ts +++ b/apps/api-extractor/src/generators/ApiModelGenerator.ts @@ -653,6 +653,7 @@ export class ApiModelGenerator { const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration); const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment; const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag; + const isReadonly: boolean = this._determineReadonly(astDeclaration); apiInterface = new ApiInterface({ name, @@ -660,7 +661,8 @@ export class ApiModelGenerator { releaseTag, excerptTokens, typeParameters, - extendsTokenRanges + extendsTokenRanges, + isReadonly }); parentApiItem.addMember(apiInterface); @@ -669,6 +671,15 @@ export class ApiModelGenerator { this._processChildDeclarations(astDeclaration, exportedName, apiInterface); } + private _determineReadonly(astDeclaration: AstDeclaration): boolean { + const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration); + const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment; + const declarationMetadata: DeclarationMetadata = this._collector.fetchDeclarationMetadata(astDeclaration); + return (astDeclaration.modifierFlags & ts.ModifierFlags.Readonly) !== 0 + || (docComment !== undefined && docComment.modifierTagSet.hasTagName('@readonly')) + || (declarationMetadata.ancillaryDeclarations.length === 0 && astDeclaration.declaration.kind === ts.SyntaxKind.GetAccessor); + } + private _processApiMethod( astDeclaration: AstDeclaration, exportedName: string | undefined, @@ -709,6 +720,7 @@ export class ApiModelGenerator { } const isOptional: boolean = (astDeclaration.astSymbol.followedSymbol.flags & ts.SymbolFlags.Optional) !== 0; + const isReadonly: boolean = this._determineReadonly(astDeclaration); apiMethod = new ApiMethod({ name, @@ -720,7 +732,8 @@ export class ApiModelGenerator { parameters, overloadIndex, excerptTokens, - returnTypeTokenRange + returnTypeTokenRange, + isReadonly }); parentApiItem.addMember(apiMethod); @@ -765,6 +778,7 @@ export class ApiModelGenerator { const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag; const isOptional: boolean = (astDeclaration.astSymbol.followedSymbol.flags & ts.SymbolFlags.Optional) !== 0; + const isReadonly: boolean = this._determineReadonly(astDeclaration); apiMethodSignature = new ApiMethodSignature({ name, @@ -775,7 +789,8 @@ export class ApiModelGenerator { parameters, overloadIndex, excerptTokens, - returnTypeTokenRange + returnTypeTokenRange, + isReadonly }); parentApiItem.addMember(apiMethodSignature); @@ -839,6 +854,7 @@ export class ApiModelGenerator { const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag; const isOptional: boolean = (astDeclaration.astSymbol.followedSymbol.flags & ts.SymbolFlags.Optional) !== 0; + const isReadonly: boolean = this._determineReadonly(astDeclaration); apiProperty = new ApiProperty({ name, @@ -846,6 +862,7 @@ export class ApiModelGenerator { releaseTag, isStatic, isOptional, + isReadonly, excerptTokens, propertyTypeTokenRange }); @@ -882,6 +899,7 @@ export class ApiModelGenerator { const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag; const isOptional: boolean = (astDeclaration.astSymbol.followedSymbol.flags & ts.SymbolFlags.Optional) !== 0; + const isReadonly: boolean = this._determineReadonly(astDeclaration); apiPropertySignature = new ApiPropertySignature({ name, @@ -889,7 +907,8 @@ export class ApiModelGenerator { releaseTag, isOptional, excerptTokens, - propertyTypeTokenRange + propertyTypeTokenRange, + isReadonly }); parentApiItem.addMember(apiPropertySignature); diff --git a/build-tests/api-documenter-test/etc/api-documenter-test.api.json b/build-tests/api-documenter-test/etc/api-documenter-test.api.json index 8ec69740667..1a833cde7a3 100644 --- a/build-tests/api-documenter-test/etc/api-documenter-test.api.json +++ b/build-tests/api-documenter-test/etc/api-documenter-test.api.json @@ -190,6 +190,7 @@ "text": "export interface Constraint " } ], + "isReadonly": false, "releaseTag": "Public", "name": "Constraint", "members": [], @@ -248,6 +249,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "creationDate", @@ -270,6 +272,7 @@ "text": "export interface DefaultType " } ], + "isReadonly": false, "releaseTag": "Public", "name": "DefaultType", "members": [], @@ -398,6 +401,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -443,6 +447,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -497,6 +502,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -565,6 +571,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -616,6 +623,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -646,6 +654,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "malformedEvent", @@ -674,6 +683,7 @@ "text": ";" } ], + "isReadonly": true, "isOptional": false, "releaseTag": "Public", "name": "modifiedEvent", @@ -709,6 +719,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -747,6 +758,7 @@ "text": ";" } ], + "isReadonly": true, "isOptional": false, "releaseTag": "Public", "name": "readonlyProperty", @@ -775,6 +787,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "regularProperty", @@ -818,6 +831,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": true, "returnTypeTokenRange": { @@ -864,6 +878,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -897,6 +912,7 @@ "text": "\n\nset writeableProperty(value: string);" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "writeableProperty", @@ -924,6 +940,7 @@ "text": ");" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "writeonlyProperty", @@ -974,6 +991,7 @@ "text": "export interface DocClassInterfaceMerge " } ], + "isReadonly": false, "releaseTag": "Public", "name": "DocClassInterfaceMerge", "members": [], @@ -1430,6 +1448,7 @@ "text": "export interface IDocInterface1 " } ], + "isReadonly": false, "releaseTag": "Public", "name": "IDocInterface1", "members": [ @@ -1452,6 +1471,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "regularProperty", @@ -1482,6 +1502,7 @@ "text": " " } ], + "isReadonly": false, "releaseTag": "Public", "name": "IDocInterface2", "members": [ @@ -1503,6 +1524,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "returnTypeTokenRange": { "startIndex": 1, @@ -1531,6 +1553,7 @@ "text": "export interface IDocInterface3 " } ], + "isReadonly": false, "releaseTag": "Public", "name": "IDocInterface3", "members": [ @@ -1552,6 +1575,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "\"[not.a.symbol]\"", @@ -1587,6 +1611,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "[EcmaSmbols.example]", @@ -1726,6 +1751,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "redundantQuotes", @@ -1747,6 +1773,7 @@ "text": "export interface IDocInterface4 " } ], + "isReadonly": false, "releaseTag": "Public", "name": "IDocInterface4", "members": [ @@ -1768,6 +1795,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "Context", @@ -1799,6 +1827,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "generic", @@ -1825,6 +1854,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "numberOrFunction", @@ -1851,6 +1881,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "stringOrNumber", @@ -1872,6 +1903,7 @@ "text": "export interface IDocInterface5 " } ], + "isReadonly": false, "releaseTag": "Public", "name": "IDocInterface5", "members": [ @@ -1893,6 +1925,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "regularProperty", @@ -1914,6 +1947,7 @@ "text": "export interface IDocInterface6 " } ], + "isReadonly": false, "releaseTag": "Public", "name": "IDocInterface6", "members": [ @@ -1940,6 +1974,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "arrayProperty", @@ -1974,6 +2009,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "returnTypeTokenRange": { "startIndex": 3, @@ -2034,6 +2070,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "intersectionProperty", @@ -2060,6 +2097,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "regularProperty", @@ -2104,6 +2142,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "tupleProperty", @@ -2144,6 +2183,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "typeReferenceProperty", @@ -2180,6 +2220,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "unionProperty", @@ -2201,6 +2242,7 @@ "text": "export interface IDocInterface7 " } ], + "isReadonly": false, "releaseTag": "Public", "name": "IDocInterface7", "members": [ @@ -2222,6 +2264,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": true, "releaseTag": "Public", "name": "optionalField", @@ -2248,6 +2291,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": true, "returnTypeTokenRange": { "startIndex": 1, @@ -2276,6 +2320,7 @@ "text": ";" } ], + "isReadonly": true, "isOptional": true, "releaseTag": "Public", "name": "optionalReadonlyField", @@ -2302,6 +2347,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": true, "releaseTag": "Public", "name": "optionalUndocumentedField", @@ -2447,6 +2493,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md index 0c0a9e42f51..ffc5e8ce6c1 100644 --- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md +++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md @@ -29,13 +29,13 @@ The constructor for this class is marked as internal. Third-party code should no | Property | Modifiers | Type | Description | | --- | --- | --- | --- | | [malformedEvent](./api-documenter-test.docclass1.malformedevent.md) | | [SystemEvent](./api-documenter-test.systemevent.md) | This event should have been marked as readonly. | -| [modifiedEvent](./api-documenter-test.docclass1.modifiedevent.md) | | [SystemEvent](./api-documenter-test.systemevent.md) | This event is fired whenever the object is modified. | +| [modifiedEvent](./api-documenter-test.docclass1.modifiedevent.md) | | [SystemEvent](./api-documenter-test.systemevent.md) | \[Readonly\] This event is fired whenever the object is modified. | ## Properties | Property | Modifiers | Type | Description | | --- | --- | --- | --- | -| [readonlyProperty](./api-documenter-test.docclass1.readonlyproperty.md) | | string | | +| [readonlyProperty](./api-documenter-test.docclass1.readonlyproperty.md) | | string | \[Readonly\] | | [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. | | [writeableProperty](./api-documenter-test.docclass1.writeableproperty.md) | | string | | | [writeonlyProperty](./api-documenter-test.docclass1.writeonlyproperty.md) | | string | API Extractor will surface an ae-missing-getter finding for this property. | diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface7.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface7.md index 122ab2bb909..909082bc689 100644 --- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface7.md +++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface7.md @@ -17,7 +17,7 @@ export interface IDocInterface7 | Property | Type | Description | | --- | --- | --- | | [optionalField?](./api-documenter-test.idocinterface7.optionalfield.md) | boolean | (Optional) Description of optionalField | -| [optionalReadonlyField?](./api-documenter-test.idocinterface7.optionalreadonlyfield.md) | boolean | (Optional) Description of optionalReadonlyField | +| [optionalReadonlyField?](./api-documenter-test.idocinterface7.optionalreadonlyfield.md) | boolean | (Optional) \[Readonly\] Description of optionalReadonlyField | | [optionalUndocumentedField?](./api-documenter-test.idocinterface7.optionalundocumentedfield.md) | boolean | (Optional) | ## Methods diff --git a/build-tests/api-extractor-scenarios/config/build-config.json b/build-tests/api-extractor-scenarios/config/build-config.json index 9a5de053b85..235cccb9382 100644 --- a/build-tests/api-extractor-scenarios/config/build-config.json +++ b/build-tests/api-extractor-scenarios/config/build-config.json @@ -36,6 +36,7 @@ "internationalCharacters", "namedDefaultImport", "preapproved", + "readonlyDeclarations", "spanSorting", "typeOf", "typeOf2", diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json index 04a825b97ce..c8e3f45a70d 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json @@ -201,6 +201,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -254,6 +255,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -301,6 +303,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -403,6 +406,7 @@ "text": "export interface IInterface " } ], + "isReadonly": false, "releaseTag": "Public", "name": "IInterface", "members": [ @@ -424,6 +428,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "member", @@ -601,6 +606,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -638,6 +644,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -676,6 +683,7 @@ "text": ";" } ], + "isReadonly": true, "isOptional": false, "releaseTag": "Public", "name": "readonlyProperty", @@ -707,6 +715,7 @@ "text": "\n\nset writeableProperty(value: string);" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "writeableProperty", diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/bundledPackages/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/bundledPackages/api-extractor-scenarios.api.json index bd4b664dec1..c22d902848d 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/bundledPackages/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/bundledPackages/api-extractor-scenarios.api.json @@ -272,6 +272,7 @@ "text": ";" } ], + "isReadonly": true, "isOptional": false, "releaseTag": "Public", "name": "readonlyProperty", @@ -299,6 +300,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "writeableProperty", diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/circularImport/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/circularImport/api-extractor-scenarios.api.json index 28023b2d299..92705d87dfa 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/circularImport/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/circularImport/api-extractor-scenarios.api.json @@ -202,6 +202,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "containingFolder", @@ -250,6 +251,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "containingFolder", @@ -282,6 +284,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "files", diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/circularImport2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/circularImport2/api-extractor-scenarios.api.json index ff11b3dd9fb..572ff3b29cb 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/circularImport2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/circularImport2/api-extractor-scenarios.api.json @@ -232,6 +232,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "containingFolder", @@ -280,6 +281,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "containingFolder", @@ -312,6 +314,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "files", diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.json index 70a404789c6..c42c2c71301 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.json @@ -276,6 +276,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/api-extractor-scenarios.api.json index 80a235676d1..84f26614b33 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/api-extractor-scenarios.api.json @@ -201,6 +201,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -230,6 +231,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -275,6 +277,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -304,6 +307,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -349,6 +353,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -378,6 +383,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json index b55e821b03e..d134f9c4b9c 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json @@ -180,6 +180,7 @@ "text": "export interface A " } ], + "isReadonly": false, "releaseTag": "Public", "name": "A", "members": [ @@ -201,6 +202,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "myProperty", @@ -256,6 +258,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType/api-extractor-scenarios.api.json index 0e22255bdfb..f04074f5adf 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType/api-extractor-scenarios.api.json @@ -206,6 +206,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "lib1", @@ -238,6 +239,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "lib2", @@ -270,6 +272,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "lib3", @@ -302,6 +305,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "options", @@ -334,6 +338,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "reExport", diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType2/api-extractor-scenarios.api.json index 26e66c9a3f3..c75b996f86a 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType2/api-extractor-scenarios.api.json @@ -180,6 +180,7 @@ "text": "export interface IExample " } ], + "isReadonly": false, "releaseTag": "Public", "name": "IExample", "members": [ @@ -210,6 +211,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "dottedImportType", @@ -245,6 +247,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "dottedImportType2", diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType3/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType3/api-extractor-scenarios.api.json index ac8ea1aba01..1e90af4e43f 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType3/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType3/api-extractor-scenarios.api.json @@ -180,6 +180,7 @@ "text": "export interface IExample " } ], + "isReadonly": false, "releaseTag": "Public", "name": "IExample", "members": [ @@ -219,6 +220,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "generic", diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/excerptTokens/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/excerptTokens/api-extractor-scenarios.api.json index 2c657737d6b..5900124b30c 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/excerptTokens/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/excerptTokens/api-extractor-scenarios.api.json @@ -238,6 +238,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/exportEquals/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/exportEquals/api-extractor-scenarios.api.json index 8cc6e3df22d..11896a8ea70 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/exportEquals/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/exportEquals/api-extractor-scenarios.api.json @@ -180,6 +180,7 @@ "text": "export interface ITeamsContext " } ], + "isReadonly": false, "releaseTag": "Public", "name": "ITeamsContext", "members": [ @@ -202,6 +203,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "context", diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/functionOverload/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/functionOverload/api-extractor-scenarios.api.json index ddb53fa73eb..c8a2b46ec96 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/functionOverload/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/functionOverload/api-extractor-scenarios.api.json @@ -397,6 +397,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -459,6 +460,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/importType/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/importType/api-extractor-scenarios.api.json index 5f4bad149d0..fdc4caff1bb 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/importType/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/importType/api-extractor-scenarios.api.json @@ -189,6 +189,7 @@ "text": " " } ], + "isReadonly": false, "releaseTag": "Public", "name": "A", "members": [], @@ -218,6 +219,7 @@ "text": " " } ], + "isReadonly": false, "releaseTag": "Public", "name": "B", "members": [], @@ -247,6 +249,7 @@ "text": " " } ], + "isReadonly": false, "releaseTag": "Public", "name": "C", "members": [], diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/inconsistentReleaseTags/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/inconsistentReleaseTags/api-extractor-scenarios.api.json index 6bf7c13e006..cdd3d6e9027 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/inconsistentReleaseTags/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/inconsistentReleaseTags/api-extractor-scenarios.api.json @@ -180,6 +180,7 @@ "text": "export interface IBeta " } ], + "isReadonly": false, "releaseTag": "Beta", "name": "IBeta", "members": [ @@ -201,6 +202,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Beta", "name": "x", diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/internationalCharacters/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/internationalCharacters/api-extractor-scenarios.api.json index 1d9fd5abb8f..61146f83b48 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/internationalCharacters/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/internationalCharacters/api-extractor-scenarios.api.json @@ -210,6 +210,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -261,6 +262,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -299,6 +301,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/namedDefaultImport/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/namedDefaultImport/api-extractor-scenarios.api.json index 4b30b3f14fb..aad217a5452 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/namedDefaultImport/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/namedDefaultImport/api-extractor-scenarios.api.json @@ -180,6 +180,7 @@ "text": "export interface DefaultImportTypes " } ], + "isReadonly": false, "releaseTag": "Public", "name": "DefaultImportTypes", "members": [ @@ -206,6 +207,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "dynamicImport", @@ -233,6 +235,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "namedImport", @@ -260,6 +263,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "reExport", diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json new file mode 100644 index 00000000000..352d671c906 --- /dev/null +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json @@ -0,0 +1,365 @@ +{ + "metadata": { + "toolPackage": "@microsoft/api-extractor", + "toolVersion": "[test mode]", + "schemaVersion": 1005, + "oldestForwardsCompatibleVersion": 1001, + "tsdocConfig": { + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "noStandardTags": true, + "tagDefinitions": [ + { + "tagName": "@alpha", + "syntaxKind": "modifier" + }, + { + "tagName": "@beta", + "syntaxKind": "modifier" + }, + { + "tagName": "@defaultValue", + "syntaxKind": "block" + }, + { + "tagName": "@decorator", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@deprecated", + "syntaxKind": "block" + }, + { + "tagName": "@eventProperty", + "syntaxKind": "modifier" + }, + { + "tagName": "@example", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@experimental", + "syntaxKind": "modifier" + }, + { + "tagName": "@inheritDoc", + "syntaxKind": "inline" + }, + { + "tagName": "@internal", + "syntaxKind": "modifier" + }, + { + "tagName": "@label", + "syntaxKind": "inline" + }, + { + "tagName": "@link", + "syntaxKind": "inline", + "allowMultiple": true + }, + { + "tagName": "@override", + "syntaxKind": "modifier" + }, + { + "tagName": "@packageDocumentation", + "syntaxKind": "modifier" + }, + { + "tagName": "@param", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@privateRemarks", + "syntaxKind": "block" + }, + { + "tagName": "@public", + "syntaxKind": "modifier" + }, + { + "tagName": "@readonly", + "syntaxKind": "modifier" + }, + { + "tagName": "@remarks", + "syntaxKind": "block" + }, + { + "tagName": "@returns", + "syntaxKind": "block" + }, + { + "tagName": "@sealed", + "syntaxKind": "modifier" + }, + { + "tagName": "@see", + "syntaxKind": "block" + }, + { + "tagName": "@throws", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@typeParam", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@virtual", + "syntaxKind": "modifier" + }, + { + "tagName": "@betaDocumentation", + "syntaxKind": "modifier" + }, + { + "tagName": "@internalRemarks", + "syntaxKind": "block" + }, + { + "tagName": "@preapproved", + "syntaxKind": "modifier" + } + ], + "supportForTags": { + "@alpha": true, + "@beta": true, + "@defaultValue": true, + "@decorator": true, + "@deprecated": true, + "@eventProperty": true, + "@example": true, + "@experimental": true, + "@inheritDoc": true, + "@internal": true, + "@label": true, + "@link": true, + "@override": true, + "@packageDocumentation": true, + "@param": true, + "@privateRemarks": true, + "@public": true, + "@readonly": true, + "@remarks": true, + "@returns": true, + "@sealed": true, + "@see": true, + "@throws": true, + "@typeParam": true, + "@virtual": true, + "@betaDocumentation": true, + "@internalRemarks": true, + "@preapproved": true + }, + "reportUnsupportedHtmlElements": false + } + }, + "kind": "Package", + "canonicalReference": "api-extractor-scenarios!", + "docComment": "", + "name": "api-extractor-scenarios", + "members": [ + { + "kind": "EntryPoint", + "canonicalReference": "api-extractor-scenarios!", + "name": "", + "members": [ + { + "kind": "Interface", + "canonicalReference": "api-extractor-scenarios!_IInternalThing:interface", + "docComment": "/**\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export interface _IInternalThing " + } + ], + "isReadonly": false, + "releaseTag": "Public", + "name": "_IInternalThing", + "members": [ + { + "kind": "PropertySignature", + "canonicalReference": "api-extractor-scenarios!_IInternalThing#title:member", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "title: " + }, + { + "kind": "Content", + "text": "string" + }, + { + "kind": "Content", + "text": ";" + } + ], + "isReadonly": false, + "isOptional": false, + "releaseTag": "Public", + "name": "title", + "propertyTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + } + } + ], + "extendsTokenRanges": [] + }, + { + "kind": "Class", + "canonicalReference": "api-extractor-scenarios!MyClass:class", + "docComment": "/**\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare class MyClass " + } + ], + "releaseTag": "Public", + "name": "MyClass", + "members": [ + { + "kind": "Property", + "canonicalReference": "api-extractor-scenarios!MyClass#_onlyHasGetterThing:member", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "get _onlyHasGetterThing(): " + }, + { + "kind": "Reference", + "text": "_IInternalThing", + "canonicalReference": "api-extractor-scenarios!_IInternalThing:interface" + }, + { + "kind": "Content", + "text": ";" + } + ], + "isReadonly": true, + "isOptional": false, + "releaseTag": "Public", + "name": "_onlyHasGetterThing", + "propertyTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "isStatic": false + }, + { + "kind": "Property", + "canonicalReference": "api-extractor-scenarios!MyClass#_writableThing:member", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "get _writableThing(): " + }, + { + "kind": "Reference", + "text": "_IInternalThing", + "canonicalReference": "api-extractor-scenarios!_IInternalThing:interface" + }, + { + "kind": "Content", + "text": ";" + }, + { + "kind": "Content", + "text": "\n\nset _writableThing(value: " + }, + { + "kind": "Reference", + "text": "_IInternalThing", + "canonicalReference": "api-extractor-scenarios!_IInternalThing:interface" + }, + { + "kind": "Content", + "text": ");" + } + ], + "isReadonly": false, + "isOptional": false, + "releaseTag": "Public", + "name": "_writableThing", + "propertyTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "isStatic": false + }, + { + "kind": "Property", + "canonicalReference": "api-extractor-scenarios!MyClass#declaredReadonlyThing:member", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "readonly declaredReadonlyThing: " + }, + { + "kind": "Reference", + "text": "_IInternalThing", + "canonicalReference": "api-extractor-scenarios!_IInternalThing:interface" + }, + { + "kind": "Content", + "text": ";" + } + ], + "isReadonly": true, + "isOptional": false, + "releaseTag": "Public", + "name": "declaredReadonlyThing", + "propertyTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "isStatic": false + }, + { + "kind": "Property", + "canonicalReference": "api-extractor-scenarios!MyClass#tsDocReadonlyThing:member", + "docComment": "/**\n * Technically isn't but for testing purposes\n *\n * @readonly\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "tsDocReadonlyThing: " + }, + { + "kind": "Reference", + "text": "_IInternalThing", + "canonicalReference": "api-extractor-scenarios!_IInternalThing:interface" + }, + { + "kind": "Content", + "text": ";" + } + ], + "isReadonly": true, + "isOptional": false, + "releaseTag": "Public", + "name": "tsDocReadonlyThing", + "propertyTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "isStatic": false + } + ], + "implementsTokenRanges": [] + } + ] + } + ] +} diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.md b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.md new file mode 100644 index 00000000000..5f28951b11b --- /dev/null +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.md @@ -0,0 +1,27 @@ +## API Report File for "api-extractor-scenarios" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts + +// @public (undocumented) +export interface _IInternalThing { + // (undocumented) + title: string; +} + +// @public (undocumented) +export class MyClass { + // (undocumented) + readonly declaredReadonlyThing: _IInternalThing; + // (undocumented) + get _onlyHasGetterThing(): _IInternalThing; + tsDocReadonlyThing: _IInternalThing; + // (undocumented) + get _writableThing(): _IInternalThing; + set _writableThing(value: _IInternalThing); +} + +// (No @packageDocumentation comment for this package) + +``` diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/rollup.d.ts new file mode 100644 index 00000000000..9f7223f430b --- /dev/null +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/rollup.d.ts @@ -0,0 +1,19 @@ +/** @public */ +export declare interface _IInternalThing { + title: string; +} + +/** @public */ +export declare class MyClass { + get _writableThing(): _IInternalThing; + set _writableThing(value: _IInternalThing); + get _onlyHasGetterThing(): _IInternalThing; + readonly declaredReadonlyThing: _IInternalThing; + /** + * Technically isn't but for testing purposes + * @readonly + */ + tsDocReadonlyThing: _IInternalThing; +} + +export { } diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/api-extractor-scenarios.api.json index 2cad31ab281..2f3ce98bb78 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/api-extractor-scenarios.api.json @@ -201,6 +201,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "releaseTag": "Public", "name": "member1", @@ -233,6 +234,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -286,6 +288,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -340,6 +343,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/typeParameters/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/typeParameters/api-extractor-scenarios.api.json index 9ec55e71032..13fc149c635 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/typeParameters/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/typeParameters/api-extractor-scenarios.api.json @@ -201,6 +201,7 @@ "text": ";" } ], + "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -378,6 +379,7 @@ "text": "export interface GenericInterface " } ], + "isReadonly": false, "releaseTag": "Public", "typeParameters": [ { @@ -444,6 +446,7 @@ "text": "export interface InterfaceWithGenericCallSignature " } ], + "isReadonly": false, "releaseTag": "Public", "name": "InterfaceWithGenericCallSignature", "members": [ @@ -499,6 +502,7 @@ "text": "export interface InterfaceWithGenericConstructSignature " } ], + "isReadonly": false, "releaseTag": "Public", "name": "InterfaceWithGenericConstructSignature", "members": [ diff --git a/build-tests/api-extractor-scenarios/src/readonlyDeclarations/index.ts b/build-tests/api-extractor-scenarios/src/readonlyDeclarations/index.ts new file mode 100644 index 00000000000..7db5de11c82 --- /dev/null +++ b/build-tests/api-extractor-scenarios/src/readonlyDeclarations/index.ts @@ -0,0 +1,28 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. +// See LICENSE in the project root for license information. + +/** @public */ +export interface _IInternalThing { + title: string; +} + +/** @public */ +export class MyClass { + public get _writableThing(): _IInternalThing { + return { title: 'thing' }; + } + + public set _writableThing(value: _IInternalThing) {} + + public get _onlyHasGetterThing(): _IInternalThing { + return { title: 'thing' }; + } + + readonly declaredReadonlyThing: _IInternalThing; + + /** + * Technically isn't but for testing purposes + * @readonly + */ + public tsDocReadonlyThing: _IInternalThing; +} diff --git a/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml b/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml index 37e52e571d2..b5d818de2b1 100644 --- a/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml +++ b/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml @@ -5,13 +5,13 @@ importers: typescript-newest-test: specifiers: '@rushstack/eslint-config': file:rushstack-eslint-config-2.6.0.tgz - '@rushstack/heft': file:rushstack-heft-0.45.2.tgz + '@rushstack/heft': file:rushstack-heft-0.45.3.tgz eslint: ~8.7.0 tslint: ~5.20.1 typescript: ~4.6.3 devDependencies: '@rushstack/eslint-config': file:../temp/tarballs/rushstack-eslint-config-2.6.0.tgz_eslint@8.7.0+typescript@4.6.3 - '@rushstack/heft': file:../temp/tarballs/rushstack-heft-0.45.2.tgz + '@rushstack/heft': file:../temp/tarballs/rushstack-heft-0.45.3.tgz eslint: 8.7.0 tslint: 5.20.1_typescript@4.6.3 typescript: 4.6.3 @@ -19,13 +19,13 @@ importers: typescript-v3-test: specifiers: '@rushstack/eslint-config': file:rushstack-eslint-config-2.6.0.tgz - '@rushstack/heft': file:rushstack-heft-0.45.2.tgz + '@rushstack/heft': file:rushstack-heft-0.45.3.tgz eslint: ~8.7.0 tslint: ~5.20.1 typescript: ~4.6.3 devDependencies: '@rushstack/eslint-config': file:../temp/tarballs/rushstack-eslint-config-2.6.0.tgz_eslint@8.7.0+typescript@4.6.3 - '@rushstack/heft': file:../temp/tarballs/rushstack-heft-0.45.2.tgz + '@rushstack/heft': file:../temp/tarballs/rushstack-heft-0.45.3.tgz eslint: 8.7.0 tslint: 5.20.1_typescript@4.6.3 typescript: 4.6.3 @@ -1753,10 +1753,10 @@ packages: - typescript dev: true - file:../temp/tarballs/rushstack-heft-0.45.2.tgz: - resolution: {tarball: file:../temp/tarballs/rushstack-heft-0.45.2.tgz} + file:../temp/tarballs/rushstack-heft-0.45.3.tgz: + resolution: {tarball: file:../temp/tarballs/rushstack-heft-0.45.3.tgz} name: '@rushstack/heft' - version: 0.45.2 + version: 0.45.3 engines: {node: '>=10.13.0'} hasBin: true dependencies: diff --git a/common/changes/@microsoft/api-documenter/api-readonly-mixin_2022-05-19-20-18.json b/common/changes/@microsoft/api-documenter/api-readonly-mixin_2022-05-19-20-18.json new file mode 100644 index 00000000000..97ef7f06558 --- /dev/null +++ b/common/changes/@microsoft/api-documenter/api-readonly-mixin_2022-05-19-20-18.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "packageName": "@microsoft/api-documenter", + "comment": "Adding readonlyMixin for Api Extractor", + "type": "patch" + } + ], + "packageName": "@microsoft/api-documenter" +} \ No newline at end of file diff --git a/common/changes/@microsoft/api-extractor-model/api-readonly-mixin_2022-05-19-20-18.json b/common/changes/@microsoft/api-extractor-model/api-readonly-mixin_2022-05-19-20-18.json new file mode 100644 index 00000000000..d68c0e4f2ad --- /dev/null +++ b/common/changes/@microsoft/api-extractor-model/api-readonly-mixin_2022-05-19-20-18.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "packageName": "@microsoft/api-extractor-model", + "comment": "Adding readonlyMixin for Api Extractor", + "type": "patch" + } + ], + "packageName": "@microsoft/api-extractor-model" +} \ No newline at end of file diff --git a/common/changes/@microsoft/api-extractor/api-readonly-mixin_2022-05-19-20-18.json b/common/changes/@microsoft/api-extractor/api-readonly-mixin_2022-05-19-20-18.json new file mode 100644 index 00000000000..841b3fbb0ba --- /dev/null +++ b/common/changes/@microsoft/api-extractor/api-readonly-mixin_2022-05-19-20-18.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "packageName": "@microsoft/api-extractor", + "comment": "Adding readonlyMixin for Api Extractor", + "type": "patch" + } + ], + "packageName": "@microsoft/api-extractor" +} \ No newline at end of file diff --git a/common/reviews/api/api-extractor-model.api.md b/common/reviews/api/api-extractor-model.api.md index e1d82ae959e..51f237e3cce 100644 --- a/common/reviews/api/api-extractor-model.api.md +++ b/common/reviews/api/api-extractor-model.api.md @@ -507,6 +507,22 @@ export class ApiPropertySignature extends ApiPropertyItem { get kind(): ApiItemKind; } +// @public +export function ApiReadonlyMixin(baseClass: TBaseClass): TBaseClass & (new (...args: any[]) => ApiReadonlyMixin); + +// @public +export interface ApiReadonlyMixin extends ApiItem { + // (undocumented) + readonly isReadonly: boolean; + // (undocumented) + serializeInto(jsonObject: Partial): void; +} + +// @public +export namespace ApiReadonlyMixin { + export function isBaseClassOf(apiItem: ApiItem): apiItem is ApiReadonlyMixin; +} + // @public export function ApiReleaseTagMixin(baseClass: TBaseClass): TBaseClass & (new (...args: any[]) => ApiReleaseTagMixin); @@ -701,7 +717,7 @@ export interface IApiIndexSignatureOptions extends IApiParameterListMixinOptions } // @public -export interface IApiInterfaceOptions extends IApiItemContainerMixinOptions, IApiNameMixinOptions, IApiTypeParameterListMixinOptions, IApiReleaseTagMixinOptions, IApiDeclaredItemOptions { +export interface IApiInterfaceOptions extends IApiItemContainerMixinOptions, IApiNameMixinOptions, IApiTypeParameterListMixinOptions, IApiReleaseTagMixinOptions, IApiDeclaredItemOptions, IApiReadonlyMixinOptions { // (undocumented) extendsTokenRanges: IExcerptTokenRange[]; } @@ -721,11 +737,11 @@ export interface IApiItemOptions { } // @public -export interface IApiMethodOptions extends IApiNameMixinOptions, IApiTypeParameterListMixinOptions, IApiParameterListMixinOptions, IApiReleaseTagMixinOptions, IApiReturnTypeMixinOptions, IApiStaticMixinOptions, IApiOptionalMixinOptions, IApiDeclaredItemOptions { +export interface IApiMethodOptions extends IApiNameMixinOptions, IApiTypeParameterListMixinOptions, IApiParameterListMixinOptions, IApiReleaseTagMixinOptions, IApiReturnTypeMixinOptions, IApiStaticMixinOptions, IApiOptionalMixinOptions, IApiReadonlyMixinOptions, IApiDeclaredItemOptions { } // @public (undocumented) -export interface IApiMethodSignatureOptions extends IApiNameMixinOptions, IApiTypeParameterListMixinOptions, IApiParameterListMixinOptions, IApiReleaseTagMixinOptions, IApiReturnTypeMixinOptions, IApiOptionalMixinOptions, IApiDeclaredItemOptions { +export interface IApiMethodSignatureOptions extends IApiNameMixinOptions, IApiTypeParameterListMixinOptions, IApiParameterListMixinOptions, IApiReleaseTagMixinOptions, IApiReturnTypeMixinOptions, IApiOptionalMixinOptions, IApiReadonlyMixinOptions, IApiDeclaredItemOptions { } // @public @@ -776,19 +792,25 @@ export interface IApiParameterOptions { } // @public -export interface IApiPropertyItemOptions extends IApiNameMixinOptions, IApiReleaseTagMixinOptions, IApiOptionalMixinOptions, IApiDeclaredItemOptions { +export interface IApiPropertyItemOptions extends IApiNameMixinOptions, IApiReleaseTagMixinOptions, IApiOptionalMixinOptions, IApiReadonlyMixinOptions, IApiDeclaredItemOptions { // (undocumented) propertyTypeTokenRange: IExcerptTokenRange; } // @public -export interface IApiPropertyOptions extends IApiPropertyItemOptions, IApiStaticMixinOptions { +export interface IApiPropertyOptions extends IApiPropertyItemOptions, IApiReadonlyMixinOptions, IApiStaticMixinOptions { } // @public export interface IApiPropertySignatureOptions extends IApiPropertyItemOptions { } +// @public +export interface IApiReadonlyMixinOptions extends IApiItemOptions { + // (undocumented) + isReadonly: boolean; +} + // @public export interface IApiReleaseTagMixinOptions extends IApiItemOptions { // (undocumented) diff --git a/libraries/api-extractor-model/src/index.ts b/libraries/api-extractor-model/src/index.ts index e80ec542d08..d960feb2466 100644 --- a/libraries/api-extractor-model/src/index.ts +++ b/libraries/api-extractor-model/src/index.ts @@ -36,6 +36,7 @@ export { IApiReturnTypeMixinOptions, ApiReturnTypeMixin } from './mixins/ApiRetu export { IApiStaticMixinOptions, ApiStaticMixin } from './mixins/ApiStaticMixin'; export { IApiNameMixinOptions, ApiNameMixin } from './mixins/ApiNameMixin'; export { IApiOptionalMixinOptions, ApiOptionalMixin } from './mixins/ApiOptionalMixin'; +export { IApiReadonlyMixinOptions, ApiReadonlyMixin } from './mixins/ApiReadonlyMixin'; export { ExcerptTokenKind, IExcerptTokenRange, IExcerptToken, ExcerptToken, Excerpt } from './mixins/Excerpt'; export { Constructor, PropertiesOf } from './mixins/Mixin'; diff --git a/libraries/api-extractor-model/src/items/ApiPropertyItem.ts b/libraries/api-extractor-model/src/items/ApiPropertyItem.ts index 9290f5deff4..9a9cfefd650 100644 --- a/libraries/api-extractor-model/src/items/ApiPropertyItem.ts +++ b/libraries/api-extractor-model/src/items/ApiPropertyItem.ts @@ -7,6 +7,7 @@ import { ApiReleaseTagMixin, IApiReleaseTagMixinOptions } from '../mixins/ApiRel import { IApiNameMixinOptions, ApiNameMixin } from '../mixins/ApiNameMixin'; import { DeserializerContext } from '../model/DeserializerContext'; import { ApiOptionalMixin, IApiOptionalMixinOptions } from '../mixins/ApiOptionalMixin'; +import { ApiReadonlyMixin, IApiReadonlyMixinOptions } from '../mixins/ApiReadonlyMixin'; /** * Constructor options for {@link ApiPropertyItem}. @@ -16,6 +17,7 @@ export interface IApiPropertyItemOptions extends IApiNameMixinOptions, IApiReleaseTagMixinOptions, IApiOptionalMixinOptions, + IApiReadonlyMixinOptions, IApiDeclaredItemOptions { propertyTypeTokenRange: IExcerptTokenRange; } @@ -29,7 +31,9 @@ export interface IApiPropertyItemJson extends IApiDeclaredItemJson { * * @public */ -export class ApiPropertyItem extends ApiNameMixin(ApiReleaseTagMixin(ApiOptionalMixin(ApiDeclaredItem))) { +export class ApiPropertyItem extends ApiNameMixin( + ApiReleaseTagMixin(ApiOptionalMixin(ApiReadonlyMixin(ApiDeclaredItem))) +) { /** * An {@link Excerpt} that describes the type of the property. */ diff --git a/libraries/api-extractor-model/src/mixins/ApiReadonlyMixin.ts b/libraries/api-extractor-model/src/mixins/ApiReadonlyMixin.ts new file mode 100644 index 00000000000..c003efbd047 --- /dev/null +++ b/libraries/api-extractor-model/src/mixins/ApiReadonlyMixin.ts @@ -0,0 +1,110 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. +// See LICENSE in the project root for license information.s + +import { ApiItem, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../items/ApiItem'; +import { DeserializerContext } from '../model/DeserializerContext'; + +/** + * Constructor options for {@link (ApiReadonlyMixin:interface)}. + * @public + */ +export interface IApiReadonlyMixinOptions extends IApiItemOptions { + isReadonly: boolean; +} + +export interface IApiReadonlyMixinJson extends IApiItemJson { + isReadonly: boolean; +} + +const _isReadonly: unique symbol = Symbol('ApiReadonlyMixin._isReadonly'); + +/** + * The mixin base class for API items that can have type parameters. + * + * @remarks + * + * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of + * API declarations. The non-abstract classes (e.g. `ApiClass`, `ApiEnum`, `ApiInterface`, etc.) use + * TypeScript "mixin" functions (e.g. `ApiDeclaredItem`, `ApiItemContainerMixin`, etc.) to add various + * features that cannot be represented as a normal inheritance chain (since TypeScript does not allow a child class + * to extend more than one base class). The "mixin" is a TypeScript merged declaration with three components: + * the function that generates a subclass, an interface that describes the members of the subclass, and + * a namespace containing static members of the class. + * + * @public + */ +// eslint-disable-next-line @typescript-eslint/naming-convention +export interface ApiReadonlyMixin extends ApiItem { + readonly isReadonly: boolean; + + serializeInto(jsonObject: Partial): void; +} + +/** + * Mixin function for {@link (ApiReadonlyMixin:interface)}. + * + * @param baseClass - The base class to be extended + * @returns A child class that extends baseClass, adding the {@link (ApiReadonlyMixin:interface)} + * functionality. + * + * @public + */ +export function ApiReadonlyMixin( + baseClass: TBaseClass + // eslint-disable-next-line @typescript-eslint/no-explicit-any +): TBaseClass & (new (...args: any[]) => ApiReadonlyMixin) { + class MixedClass extends baseClass implements ApiReadonlyMixin { + public [_isReadonly]: boolean; + + // eslint-disable-next-line @typescript-eslint/no-explicit-any + public constructor(...args: any[]) { + super(...args); + + const options: IApiReadonlyMixinOptions = args[0]; + this[_isReadonly] = options.isReadonly; + } + + /** @override */ + public static onDeserializeInto( + options: Partial, + context: DeserializerContext, + jsonObject: IApiReadonlyMixinJson + ): void { + baseClass.onDeserializeInto(options, context, jsonObject); + + options.isReadonly = jsonObject.isReadonly || false; + } + + public get isReadonly(): boolean { + return this[_isReadonly]; + } + + /** @override */ + public serializeInto(jsonObject: Partial): void { + super.serializeInto(jsonObject); + + jsonObject.isReadonly = this.isReadonly; + } + } + + return MixedClass; +} + +/** + * Static members for {@link (ApiReadonlyMixin:interface)}. + * @public + */ +export namespace ApiReadonlyMixin { + /** + * A type guard that tests whether the specified `ApiItem` subclass extends the `ApiReadonlyMixin` mixin. + * + * @remarks + * + * The JavaScript `instanceof` operator cannot be used to test for mixin inheritance, because each invocation of + * the mixin function produces a different subclass. (This could be mitigated by `Symbol.hasInstance`, however + * the TypeScript type system cannot invoke a runtime test.) + */ + export function isBaseClassOf(apiItem: ApiItem): apiItem is ApiReadonlyMixin { + return apiItem.hasOwnProperty(_isReadonly); + } +} diff --git a/libraries/api-extractor-model/src/model/ApiInterface.ts b/libraries/api-extractor-model/src/model/ApiInterface.ts index bef31906e2e..58960adfe2a 100644 --- a/libraries/api-extractor-model/src/model/ApiInterface.ts +++ b/libraries/api-extractor-model/src/model/ApiInterface.ts @@ -27,6 +27,7 @@ import { IApiTypeParameterListMixinJson, ApiTypeParameterListMixin } from '../mixins/ApiTypeParameterListMixin'; +import { ApiReadonlyMixin, IApiReadonlyMixinOptions } from '../mixins/ApiReadonlyMixin'; import { DeserializerContext } from './DeserializerContext'; /** @@ -38,7 +39,8 @@ export interface IApiInterfaceOptions IApiNameMixinOptions, IApiTypeParameterListMixinOptions, IApiReleaseTagMixinOptions, - IApiDeclaredItemOptions { + IApiDeclaredItemOptions, + IApiReadonlyMixinOptions { extendsTokenRanges: IExcerptTokenRange[]; } @@ -69,7 +71,7 @@ export interface IApiInterfaceJson * @public */ export class ApiInterface extends ApiItemContainerMixin( - ApiNameMixin(ApiTypeParameterListMixin(ApiReleaseTagMixin(ApiDeclaredItem))) + ApiNameMixin(ApiTypeParameterListMixin(ApiReleaseTagMixin(ApiReadonlyMixin(ApiDeclaredItem)))) ) { private readonly _extendsTypes: HeritageType[] = []; diff --git a/libraries/api-extractor-model/src/model/ApiMethod.ts b/libraries/api-extractor-model/src/model/ApiMethod.ts index fbfe2c4a8e2..567a5e362de 100644 --- a/libraries/api-extractor-model/src/model/ApiMethod.ts +++ b/libraries/api-extractor-model/src/model/ApiMethod.ts @@ -19,6 +19,7 @@ import { IApiTypeParameterListMixinOptions } from '../mixins/ApiTypeParameterListMixin'; import { ApiOptionalMixin, IApiOptionalMixinOptions } from '../mixins/ApiOptionalMixin'; +import { ApiReadonlyMixin, IApiReadonlyMixinOptions } from '../mixins/ApiReadonlyMixin'; /** * Constructor options for {@link ApiMethod}. @@ -32,6 +33,7 @@ export interface IApiMethodOptions IApiReturnTypeMixinOptions, IApiStaticMixinOptions, IApiOptionalMixinOptions, + IApiReadonlyMixinOptions, IApiDeclaredItemOptions {} /** @@ -58,7 +60,9 @@ export interface IApiMethodOptions export class ApiMethod extends ApiNameMixin( ApiTypeParameterListMixin( ApiParameterListMixin( - ApiReleaseTagMixin(ApiReturnTypeMixin(ApiStaticMixin(ApiOptionalMixin(ApiDeclaredItem)))) + ApiReleaseTagMixin( + ApiReturnTypeMixin(ApiStaticMixin(ApiOptionalMixin(ApiReadonlyMixin(ApiDeclaredItem)))) + ) ) ) ) { diff --git a/libraries/api-extractor-model/src/model/ApiMethodSignature.ts b/libraries/api-extractor-model/src/model/ApiMethodSignature.ts index caf8541b028..b7a56aa7a94 100644 --- a/libraries/api-extractor-model/src/model/ApiMethodSignature.ts +++ b/libraries/api-extractor-model/src/model/ApiMethodSignature.ts @@ -18,6 +18,7 @@ import { ApiTypeParameterListMixin } from '../mixins/ApiTypeParameterListMixin'; import { ApiOptionalMixin, IApiOptionalMixinOptions } from '../mixins/ApiOptionalMixin'; +import { ApiReadonlyMixin, IApiReadonlyMixinOptions } from '../mixins/ApiReadonlyMixin'; /** @public */ export interface IApiMethodSignatureOptions @@ -27,6 +28,7 @@ export interface IApiMethodSignatureOptions IApiReleaseTagMixinOptions, IApiReturnTypeMixinOptions, IApiOptionalMixinOptions, + IApiReadonlyMixinOptions, IApiDeclaredItemOptions {} /** @@ -52,7 +54,9 @@ export interface IApiMethodSignatureOptions */ export class ApiMethodSignature extends ApiNameMixin( ApiTypeParameterListMixin( - ApiParameterListMixin(ApiReleaseTagMixin(ApiReturnTypeMixin(ApiOptionalMixin(ApiDeclaredItem)))) + ApiParameterListMixin( + ApiReleaseTagMixin(ApiReturnTypeMixin(ApiOptionalMixin(ApiReadonlyMixin(ApiDeclaredItem)))) + ) ) ) { public constructor(options: IApiMethodSignatureOptions) { diff --git a/libraries/api-extractor-model/src/model/ApiProperty.ts b/libraries/api-extractor-model/src/model/ApiProperty.ts index 5b6bb184d05..d0799e048f6 100644 --- a/libraries/api-extractor-model/src/model/ApiProperty.ts +++ b/libraries/api-extractor-model/src/model/ApiProperty.ts @@ -8,6 +8,7 @@ import { Component } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference'; import { ApiItemKind } from '../items/ApiItem'; +import { ApiReadonlyMixin, IApiReadonlyMixinOptions } from '../mixins/ApiReadonlyMixin'; import { ApiStaticMixin, IApiStaticMixinOptions } from '../mixins/ApiStaticMixin'; import { ApiPropertyItem, IApiPropertyItemOptions } from '../items/ApiPropertyItem'; @@ -15,7 +16,7 @@ import { ApiPropertyItem, IApiPropertyItemOptions } from '../items/ApiPropertyIt * Constructor options for {@link ApiProperty}. * @public */ -export interface IApiPropertyOptions extends IApiPropertyItemOptions, IApiStaticMixinOptions {} +export interface IApiPropertyOptions extends IApiPropertyItemOptions, IApiReadonlyMixinOptions, IApiStaticMixinOptions {} /** * Represents a TypeScript property declaration that belongs to an `ApiClass`. @@ -51,7 +52,7 @@ export interface IApiPropertyOptions extends IApiPropertyItemOptions, IApiStatic * * @public */ -export class ApiProperty extends ApiStaticMixin(ApiPropertyItem) { +export class ApiProperty extends ApiReadonlyMixin(ApiStaticMixin(ApiPropertyItem)) { public constructor(options: IApiPropertyOptions) { super(options); } From 02612834883ea980812d69710be423777cffddc0 Mon Sep 17 00:00:00 2001 From: mrshllstock Date: Thu, 19 May 2022 17:52:53 -0700 Subject: [PATCH 02/14] [api-extractor] addressing comments --- apps/api-extractor/src/generators/ApiModelGenerator.ts | 9 +++++---- .../etc/api-documenter-test.api.json | 10 ---------- .../apiItemKinds/api-extractor-scenarios.api.json | 1 - .../docReferences3/api-extractor-scenarios.api.json | 1 - .../api-extractor-scenarios.api.json | 1 - .../api-extractor-scenarios.api.json | 1 - .../exportEquals/api-extractor-scenarios.api.json | 1 - .../importType/api-extractor-scenarios.api.json | 3 --- .../api-extractor-scenarios.api.json | 1 - .../api-extractor-scenarios.api.json | 1 - .../api-extractor-scenarios.api.json | 1 - .../typeParameters/api-extractor-scenarios.api.json | 3 --- .../api-readonly-mixin_2022-05-19-20-18.json | 4 ++-- .../api-readonly-mixin_2022-05-19-20-18.json | 4 ++-- .../api-readonly-mixin_2022-05-19-20-18.json | 2 +- common/reviews/api/api-extractor-model.api.md | 8 +++++--- .../api-extractor-model/src/mixins/ApiReadonlyMixin.ts | 3 ++- .../api-extractor-model/src/model/ApiInterface.ts | 6 ++---- .../src/model/ApiPropertySignature.ts | 6 +++--- 19 files changed, 22 insertions(+), 44 deletions(-) diff --git a/apps/api-extractor/src/generators/ApiModelGenerator.ts b/apps/api-extractor/src/generators/ApiModelGenerator.ts index 1119ae7c41c..436d1a20245 100644 --- a/apps/api-extractor/src/generators/ApiModelGenerator.ts +++ b/apps/api-extractor/src/generators/ApiModelGenerator.ts @@ -653,7 +653,6 @@ export class ApiModelGenerator { const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration); const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment; const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag; - const isReadonly: boolean = this._determineReadonly(astDeclaration); apiInterface = new ApiInterface({ name, @@ -661,8 +660,7 @@ export class ApiModelGenerator { releaseTag, excerptTokens, typeParameters, - extendsTokenRanges, - isReadonly + extendsTokenRanges }); parentApiItem.addMember(apiInterface); @@ -675,8 +673,11 @@ export class ApiModelGenerator { const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration); const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment; const declarationMetadata: DeclarationMetadata = this._collector.fetchDeclarationMetadata(astDeclaration); + //Line 1: sees whether the readonly modifier is present + //Line 2: sees if the TSDoc comment for @readonly is present + //Line 3: sees whether a getter is present for a property with no setter return (astDeclaration.modifierFlags & ts.ModifierFlags.Readonly) !== 0 - || (docComment !== undefined && docComment.modifierTagSet.hasTagName('@readonly')) + || (docComment !== undefined && docComment.modifierTagSet.hasTagName('@readonly')) || (declarationMetadata.ancillaryDeclarations.length === 0 && astDeclaration.declaration.kind === ts.SyntaxKind.GetAccessor); } diff --git a/build-tests/api-documenter-test/etc/api-documenter-test.api.json b/build-tests/api-documenter-test/etc/api-documenter-test.api.json index 1a833cde7a3..4582766332d 100644 --- a/build-tests/api-documenter-test/etc/api-documenter-test.api.json +++ b/build-tests/api-documenter-test/etc/api-documenter-test.api.json @@ -190,7 +190,6 @@ "text": "export interface Constraint " } ], - "isReadonly": false, "releaseTag": "Public", "name": "Constraint", "members": [], @@ -272,7 +271,6 @@ "text": "export interface DefaultType " } ], - "isReadonly": false, "releaseTag": "Public", "name": "DefaultType", "members": [], @@ -991,7 +989,6 @@ "text": "export interface DocClassInterfaceMerge " } ], - "isReadonly": false, "releaseTag": "Public", "name": "DocClassInterfaceMerge", "members": [], @@ -1448,7 +1445,6 @@ "text": "export interface IDocInterface1 " } ], - "isReadonly": false, "releaseTag": "Public", "name": "IDocInterface1", "members": [ @@ -1502,7 +1498,6 @@ "text": " " } ], - "isReadonly": false, "releaseTag": "Public", "name": "IDocInterface2", "members": [ @@ -1553,7 +1548,6 @@ "text": "export interface IDocInterface3 " } ], - "isReadonly": false, "releaseTag": "Public", "name": "IDocInterface3", "members": [ @@ -1773,7 +1767,6 @@ "text": "export interface IDocInterface4 " } ], - "isReadonly": false, "releaseTag": "Public", "name": "IDocInterface4", "members": [ @@ -1903,7 +1896,6 @@ "text": "export interface IDocInterface5 " } ], - "isReadonly": false, "releaseTag": "Public", "name": "IDocInterface5", "members": [ @@ -1947,7 +1939,6 @@ "text": "export interface IDocInterface6 " } ], - "isReadonly": false, "releaseTag": "Public", "name": "IDocInterface6", "members": [ @@ -2242,7 +2233,6 @@ "text": "export interface IDocInterface7 " } ], - "isReadonly": false, "releaseTag": "Public", "name": "IDocInterface7", "members": [ diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json index c8e3f45a70d..06ce168d91b 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json @@ -406,7 +406,6 @@ "text": "export interface IInterface " } ], - "isReadonly": false, "releaseTag": "Public", "name": "IInterface", "members": [ diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json index d134f9c4b9c..3cb7f34446f 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json @@ -180,7 +180,6 @@ "text": "export interface A " } ], - "isReadonly": false, "releaseTag": "Public", "name": "A", "members": [ diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType2/api-extractor-scenarios.api.json index c75b996f86a..df3313e91e3 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType2/api-extractor-scenarios.api.json @@ -180,7 +180,6 @@ "text": "export interface IExample " } ], - "isReadonly": false, "releaseTag": "Public", "name": "IExample", "members": [ diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType3/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType3/api-extractor-scenarios.api.json index 1e90af4e43f..c10066fe0b8 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType3/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/dynamicImportType3/api-extractor-scenarios.api.json @@ -180,7 +180,6 @@ "text": "export interface IExample " } ], - "isReadonly": false, "releaseTag": "Public", "name": "IExample", "members": [ diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/exportEquals/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/exportEquals/api-extractor-scenarios.api.json index 11896a8ea70..474b424f0ce 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/exportEquals/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/exportEquals/api-extractor-scenarios.api.json @@ -180,7 +180,6 @@ "text": "export interface ITeamsContext " } ], - "isReadonly": false, "releaseTag": "Public", "name": "ITeamsContext", "members": [ diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/importType/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/importType/api-extractor-scenarios.api.json index fdc4caff1bb..5f4bad149d0 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/importType/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/importType/api-extractor-scenarios.api.json @@ -189,7 +189,6 @@ "text": " " } ], - "isReadonly": false, "releaseTag": "Public", "name": "A", "members": [], @@ -219,7 +218,6 @@ "text": " " } ], - "isReadonly": false, "releaseTag": "Public", "name": "B", "members": [], @@ -249,7 +247,6 @@ "text": " " } ], - "isReadonly": false, "releaseTag": "Public", "name": "C", "members": [], diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/inconsistentReleaseTags/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/inconsistentReleaseTags/api-extractor-scenarios.api.json index cdd3d6e9027..73d67653141 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/inconsistentReleaseTags/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/inconsistentReleaseTags/api-extractor-scenarios.api.json @@ -180,7 +180,6 @@ "text": "export interface IBeta " } ], - "isReadonly": false, "releaseTag": "Beta", "name": "IBeta", "members": [ diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/namedDefaultImport/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/namedDefaultImport/api-extractor-scenarios.api.json index aad217a5452..eab7b267bed 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/namedDefaultImport/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/namedDefaultImport/api-extractor-scenarios.api.json @@ -180,7 +180,6 @@ "text": "export interface DefaultImportTypes " } ], - "isReadonly": false, "releaseTag": "Public", "name": "DefaultImportTypes", "members": [ diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json index 352d671c906..038ae040456 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json @@ -180,7 +180,6 @@ "text": "export interface _IInternalThing " } ], - "isReadonly": false, "releaseTag": "Public", "name": "_IInternalThing", "members": [ diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/typeParameters/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/typeParameters/api-extractor-scenarios.api.json index 13fc149c635..a0055cdc109 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/typeParameters/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/typeParameters/api-extractor-scenarios.api.json @@ -379,7 +379,6 @@ "text": "export interface GenericInterface " } ], - "isReadonly": false, "releaseTag": "Public", "typeParameters": [ { @@ -446,7 +445,6 @@ "text": "export interface InterfaceWithGenericCallSignature " } ], - "isReadonly": false, "releaseTag": "Public", "name": "InterfaceWithGenericCallSignature", "members": [ @@ -502,7 +500,6 @@ "text": "export interface InterfaceWithGenericConstructSignature " } ], - "isReadonly": false, "releaseTag": "Public", "name": "InterfaceWithGenericConstructSignature", "members": [ diff --git a/common/changes/@microsoft/api-documenter/api-readonly-mixin_2022-05-19-20-18.json b/common/changes/@microsoft/api-documenter/api-readonly-mixin_2022-05-19-20-18.json index 97ef7f06558..97364dbdff8 100644 --- a/common/changes/@microsoft/api-documenter/api-readonly-mixin_2022-05-19-20-18.json +++ b/common/changes/@microsoft/api-documenter/api-readonly-mixin_2022-05-19-20-18.json @@ -2,8 +2,8 @@ "changes": [ { "packageName": "@microsoft/api-documenter", - "comment": "Adding readonlyMixin for Api Extractor", - "type": "patch" + "comment": "Add support for rendering readonly information next to API items", + "type": "minor" } ], "packageName": "@microsoft/api-documenter" diff --git a/common/changes/@microsoft/api-extractor-model/api-readonly-mixin_2022-05-19-20-18.json b/common/changes/@microsoft/api-extractor-model/api-readonly-mixin_2022-05-19-20-18.json index d68c0e4f2ad..acca3ad737a 100644 --- a/common/changes/@microsoft/api-extractor-model/api-readonly-mixin_2022-05-19-20-18.json +++ b/common/changes/@microsoft/api-extractor-model/api-readonly-mixin_2022-05-19-20-18.json @@ -2,8 +2,8 @@ "changes": [ { "packageName": "@microsoft/api-extractor-model", - "comment": "Adding readonlyMixin for Api Extractor", - "type": "patch" + "comment": "Adding isReadonly field to the models of relevant api pieces.", + "type": "minor" } ], "packageName": "@microsoft/api-extractor-model" diff --git a/common/changes/@microsoft/api-extractor/api-readonly-mixin_2022-05-19-20-18.json b/common/changes/@microsoft/api-extractor/api-readonly-mixin_2022-05-19-20-18.json index 841b3fbb0ba..681547e7226 100644 --- a/common/changes/@microsoft/api-extractor/api-readonly-mixin_2022-05-19-20-18.json +++ b/common/changes/@microsoft/api-extractor/api-readonly-mixin_2022-05-19-20-18.json @@ -3,7 +3,7 @@ { "packageName": "@microsoft/api-extractor", "comment": "Adding readonlyMixin for Api Extractor", - "type": "patch" + "type": "minor" } ], "packageName": "@microsoft/api-extractor" diff --git a/common/reviews/api/api-extractor-model.api.md b/common/reviews/api/api-extractor-model.api.md index 51f237e3cce..1e9f41a4d23 100644 --- a/common/reviews/api/api-extractor-model.api.md +++ b/common/reviews/api/api-extractor-model.api.md @@ -494,8 +494,10 @@ export class ApiPropertyItem extends ApiPropertyItem_base { serializeInto(jsonObject: Partial): void; } +// Warning: (ae-forgotten-export) The symbol "ApiPropertySignature_base" needs to be exported by the entry point index.d.ts +// // @public -export class ApiPropertySignature extends ApiPropertyItem { +export class ApiPropertySignature extends ApiPropertySignature_base { constructor(options: IApiPropertySignatureOptions); // @beta @override (undocumented) buildCanonicalReference(): DeclarationReference; @@ -717,7 +719,7 @@ export interface IApiIndexSignatureOptions extends IApiParameterListMixinOptions } // @public -export interface IApiInterfaceOptions extends IApiItemContainerMixinOptions, IApiNameMixinOptions, IApiTypeParameterListMixinOptions, IApiReleaseTagMixinOptions, IApiDeclaredItemOptions, IApiReadonlyMixinOptions { +export interface IApiInterfaceOptions extends IApiItemContainerMixinOptions, IApiNameMixinOptions, IApiTypeParameterListMixinOptions, IApiReleaseTagMixinOptions, IApiDeclaredItemOptions { // (undocumented) extendsTokenRanges: IExcerptTokenRange[]; } @@ -802,7 +804,7 @@ export interface IApiPropertyOptions extends IApiPropertyItemOptions, IApiReadon } // @public -export interface IApiPropertySignatureOptions extends IApiPropertyItemOptions { +export interface IApiPropertySignatureOptions extends IApiPropertyItemOptions, IApiReadonlyMixinOptions { } // @public diff --git a/libraries/api-extractor-model/src/mixins/ApiReadonlyMixin.ts b/libraries/api-extractor-model/src/mixins/ApiReadonlyMixin.ts index c003efbd047..0c6c6069cdb 100644 --- a/libraries/api-extractor-model/src/mixins/ApiReadonlyMixin.ts +++ b/libraries/api-extractor-model/src/mixins/ApiReadonlyMixin.ts @@ -19,7 +19,8 @@ export interface IApiReadonlyMixinJson extends IApiItemJson { const _isReadonly: unique symbol = Symbol('ApiReadonlyMixin._isReadonly'); /** - * The mixin base class for API items that can have type parameters. + * The mixin base class for API items that cannot be modified after instantiation. + * Examples such as the readonly modifier and only having a getter but no setter. * * @remarks * diff --git a/libraries/api-extractor-model/src/model/ApiInterface.ts b/libraries/api-extractor-model/src/model/ApiInterface.ts index 58960adfe2a..bef31906e2e 100644 --- a/libraries/api-extractor-model/src/model/ApiInterface.ts +++ b/libraries/api-extractor-model/src/model/ApiInterface.ts @@ -27,7 +27,6 @@ import { IApiTypeParameterListMixinJson, ApiTypeParameterListMixin } from '../mixins/ApiTypeParameterListMixin'; -import { ApiReadonlyMixin, IApiReadonlyMixinOptions } from '../mixins/ApiReadonlyMixin'; import { DeserializerContext } from './DeserializerContext'; /** @@ -39,8 +38,7 @@ export interface IApiInterfaceOptions IApiNameMixinOptions, IApiTypeParameterListMixinOptions, IApiReleaseTagMixinOptions, - IApiDeclaredItemOptions, - IApiReadonlyMixinOptions { + IApiDeclaredItemOptions { extendsTokenRanges: IExcerptTokenRange[]; } @@ -71,7 +69,7 @@ export interface IApiInterfaceJson * @public */ export class ApiInterface extends ApiItemContainerMixin( - ApiNameMixin(ApiTypeParameterListMixin(ApiReleaseTagMixin(ApiReadonlyMixin(ApiDeclaredItem)))) + ApiNameMixin(ApiTypeParameterListMixin(ApiReleaseTagMixin(ApiDeclaredItem))) ) { private readonly _extendsTypes: HeritageType[] = []; diff --git a/libraries/api-extractor-model/src/model/ApiPropertySignature.ts b/libraries/api-extractor-model/src/model/ApiPropertySignature.ts index 6a5c561f840..fd9fe8836cc 100644 --- a/libraries/api-extractor-model/src/model/ApiPropertySignature.ts +++ b/libraries/api-extractor-model/src/model/ApiPropertySignature.ts @@ -9,12 +9,12 @@ import { } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference'; import { ApiItemKind } from '../items/ApiItem'; import { ApiPropertyItem, IApiPropertyItemOptions } from '../items/ApiPropertyItem'; - +import { ApiReadonlyMixin, IApiReadonlyMixinOptions } from '../mixins/ApiReadonlyMixin'; /** * Constructor options for {@link ApiPropertySignature}. * @public */ -export interface IApiPropertySignatureOptions extends IApiPropertyItemOptions {} +export interface IApiPropertySignatureOptions extends IApiPropertyItemOptions, IApiReadonlyMixinOptions {} /** * Represents a TypeScript property declaration that belongs to an `ApiInterface`. @@ -38,7 +38,7 @@ export interface IApiPropertySignatureOptions extends IApiPropertyItemOptions {} * * @public */ -export class ApiPropertySignature extends ApiPropertyItem { +export class ApiPropertySignature extends ApiReadonlyMixin(ApiPropertyItem) { public constructor(options: IApiPropertySignatureOptions) { super(options); } From a521679b70b5e932117e13c5c6510af218e5da84 Mon Sep 17 00:00:00 2001 From: mrshllstock Date: Fri, 20 May 2022 10:48:51 -0700 Subject: [PATCH 03/14] [api-extractor] Added const case for isReadonly, use mixin on enum as well --- .../src/documenters/MarkdownDocumenter.ts | 15 ++--- .../src/generators/ApiModelGenerator.ts | 27 ++++----- .../etc/api-documenter-test.api.json | 6 +- .../markdown/api-documenter-test.docclass1.md | 4 +- .../api-documenter-test.idocinterface7.md | 2 +- .../api-extractor-scenarios.api.json | 6 +- .../api-extractor-scenarios.api.json | 58 +++++++++++++++++++ .../api-extractor-scenarios.api.md | 8 +++ .../readonlyDeclarations/rollup.d.ts | 6 ++ .../src/readonlyDeclarations/index.ts | 5 ++ common/reviews/api/api-extractor-model.api.md | 2 +- .../api-extractor-model/src/model/ApiEnum.ts | 6 +- 12 files changed, 113 insertions(+), 32 deletions(-) diff --git a/apps/api-documenter/src/documenters/MarkdownDocumenter.ts b/apps/api-documenter/src/documenters/MarkdownDocumenter.ts index 9b569a28281..4c0c1378f16 100644 --- a/apps/api-documenter/src/documenters/MarkdownDocumenter.ts +++ b/apps/api-documenter/src/documenters/MarkdownDocumenter.ts @@ -998,15 +998,6 @@ export class MarkdownDocumenter { new DocPlainText({ configuration, text: ' ' }) ]); } - //Should this be under modifer or descriptions? - if (ApiReadonlyMixin.isBaseClassOf(apiItem) && apiItem.isReadonly) { - section.appendNodesInParagraph([ - new DocEmphasisSpan({ configuration, italic: true }, [ - new DocPlainText({ configuration, text: '[Readonly]' }) - ]), - new DocPlainText({ configuration, text: ' ' }) - ]); - } if (apiItem instanceof ApiDocumentedItem) { if (apiItem.tsdocComment !== undefined) { @@ -1028,6 +1019,12 @@ export class MarkdownDocumenter { } } + if (ApiReadonlyMixin.isBaseClassOf(apiItem)) { + if (apiItem.isReadonly) { + section.appendNodeInParagraph(new DocCodeSpan({ configuration, code: 'readonly' })); + } + } + return new DocTableCell({ configuration }, section.nodes); } diff --git a/apps/api-extractor/src/generators/ApiModelGenerator.ts b/apps/api-extractor/src/generators/ApiModelGenerator.ts index 436d1a20245..611b3470155 100644 --- a/apps/api-extractor/src/generators/ApiModelGenerator.ts +++ b/apps/api-extractor/src/generators/ApiModelGenerator.ts @@ -471,8 +471,9 @@ export class ApiModelGenerator { const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration); const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment; const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag; + const isReadonly: boolean = this._determineReadonly(astDeclaration); - apiEnum = new ApiEnum({ name, docComment, releaseTag, excerptTokens }); + apiEnum = new ApiEnum({ name, docComment, releaseTag, excerptTokens, isReadonly }); parentApiItem.addMember(apiEnum); } @@ -669,18 +670,6 @@ export class ApiModelGenerator { this._processChildDeclarations(astDeclaration, exportedName, apiInterface); } - private _determineReadonly(astDeclaration: AstDeclaration): boolean { - const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration); - const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment; - const declarationMetadata: DeclarationMetadata = this._collector.fetchDeclarationMetadata(astDeclaration); - //Line 1: sees whether the readonly modifier is present - //Line 2: sees if the TSDoc comment for @readonly is present - //Line 3: sees whether a getter is present for a property with no setter - return (astDeclaration.modifierFlags & ts.ModifierFlags.Readonly) !== 0 - || (docComment !== undefined && docComment.modifierTagSet.hasTagName('@readonly')) - || (declarationMetadata.ancillaryDeclarations.length === 0 && astDeclaration.declaration.kind === ts.SyntaxKind.GetAccessor); - } - private _processApiMethod( astDeclaration: AstDeclaration, exportedName: string | undefined, @@ -1062,4 +1051,16 @@ export class ApiModelGenerator { } return parameters; } + + private _determineReadonly(astDeclaration: AstDeclaration): boolean { + const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration); + const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment; + const declarationMetadata: DeclarationMetadata = this._collector.fetchDeclarationMetadata(astDeclaration); + //Line 1: sees whether the readonly or const modifiers present + //Line 2: sees if the TSDoc comment for @readonly is present + //Line 3: sees whether a getter is present for a property with no setter + return (astDeclaration.modifierFlags & (ts.ModifierFlags.Readonly + ts.ModifierFlags.Const)) !== 0 + || (docComment !== undefined && docComment.modifierTagSet.hasTagName('@readonly')) + || (declarationMetadata.ancillaryDeclarations.length === 0 && astDeclaration.declaration.kind === ts.SyntaxKind.GetAccessor); + } } diff --git a/build-tests/api-documenter-test/etc/api-documenter-test.api.json b/build-tests/api-documenter-test/etc/api-documenter-test.api.json index 4582766332d..66c12a36287 100644 --- a/build-tests/api-documenter-test/etc/api-documenter-test.api.json +++ b/build-tests/api-documenter-test/etc/api-documenter-test.api.json @@ -1070,7 +1070,8 @@ "endIndex": 2 } } - ] + ], + "isReadonly": false }, { "kind": "Enum", @@ -1127,7 +1128,8 @@ "endIndex": 2 } } - ] + ], + "isReadonly": false }, { "kind": "Namespace", diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md index ffc5e8ce6c1..478eba2e035 100644 --- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md +++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md @@ -29,13 +29,13 @@ The constructor for this class is marked as internal. Third-party code should no | Property | Modifiers | Type | Description | | --- | --- | --- | --- | | [malformedEvent](./api-documenter-test.docclass1.malformedevent.md) | | [SystemEvent](./api-documenter-test.systemevent.md) | This event should have been marked as readonly. | -| [modifiedEvent](./api-documenter-test.docclass1.modifiedevent.md) | | [SystemEvent](./api-documenter-test.systemevent.md) | \[Readonly\] This event is fired whenever the object is modified. | +| [modifiedEvent](./api-documenter-test.docclass1.modifiedevent.md) | readonly | [SystemEvent](./api-documenter-test.systemevent.md) | This event is fired whenever the object is modified. | ## Properties | Property | Modifiers | Type | Description | | --- | --- | --- | --- | -| [readonlyProperty](./api-documenter-test.docclass1.readonlyproperty.md) | | string | \[Readonly\] | +| [readonlyProperty](./api-documenter-test.docclass1.readonlyproperty.md) | readonly | string | | | [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. | | [writeableProperty](./api-documenter-test.docclass1.writeableproperty.md) | | string | | | [writeonlyProperty](./api-documenter-test.docclass1.writeonlyproperty.md) | | string | API Extractor will surface an ae-missing-getter finding for this property. | diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface7.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface7.md index 909082bc689..122ab2bb909 100644 --- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface7.md +++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface7.md @@ -17,7 +17,7 @@ export interface IDocInterface7 | Property | Type | Description | | --- | --- | --- | | [optionalField?](./api-documenter-test.idocinterface7.optionalfield.md) | boolean | (Optional) Description of optionalField | -| [optionalReadonlyField?](./api-documenter-test.idocinterface7.optionalreadonlyfield.md) | boolean | (Optional) \[Readonly\] Description of optionalReadonlyField | +| [optionalReadonlyField?](./api-documenter-test.idocinterface7.optionalreadonlyfield.md) | boolean | (Optional) Description of optionalReadonlyField | | [optionalUndocumentedField?](./api-documenter-test.idocinterface7.optionalundocumentedfield.md) | boolean | (Optional) | ## Methods diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json index 06ce168d91b..4ec3de2c917 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json @@ -394,7 +394,8 @@ "endIndex": 2 } } - ] + ], + "isReadonly": true }, { "kind": "Interface", @@ -572,7 +573,8 @@ "endIndex": 2 } } - ] + ], + "isReadonly": false }, { "kind": "Class", diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json index 038ae040456..8a0580a8789 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json @@ -213,6 +213,64 @@ ], "extendsTokenRanges": [] }, + { + "kind": "Enum", + "canonicalReference": "api-extractor-scenarios!ConstEnum:enum", + "docComment": "/**\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare const enum ConstEnum " + } + ], + "releaseTag": "Public", + "name": "ConstEnum", + "members": [ + { + "kind": "EnumMember", + "canonicalReference": "api-extractor-scenarios!ConstEnum.One:member", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "One = " + }, + { + "kind": "Content", + "text": "1" + } + ], + "releaseTag": "Public", + "name": "One", + "initializerTokenRange": { + "startIndex": 1, + "endIndex": 2 + } + }, + { + "kind": "EnumMember", + "canonicalReference": "api-extractor-scenarios!ConstEnum.Zero:member", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "Zero = " + }, + { + "kind": "Content", + "text": "0" + } + ], + "releaseTag": "Public", + "name": "Zero", + "initializerTokenRange": { + "startIndex": 1, + "endIndex": 2 + } + } + ], + "isReadonly": true + }, { "kind": "Class", "canonicalReference": "api-extractor-scenarios!MyClass:class", diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.md b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.md index 5f28951b11b..4f59fe5f876 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.md +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.md @@ -4,6 +4,14 @@ ```ts +// @public (undocumented) +export const enum ConstEnum { + // (undocumented) + One = 1, + // (undocumented) + Zero = 0 +} + // @public (undocumented) export interface _IInternalThing { // (undocumented) diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/rollup.d.ts index 9f7223f430b..bda05b2d2ef 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/rollup.d.ts +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/rollup.d.ts @@ -1,3 +1,9 @@ +/** @public */ +export declare const enum ConstEnum { + Zero = 0, + One = 1 +} + /** @public */ export declare interface _IInternalThing { title: string; diff --git a/build-tests/api-extractor-scenarios/src/readonlyDeclarations/index.ts b/build-tests/api-extractor-scenarios/src/readonlyDeclarations/index.ts index 7db5de11c82..816f9f2dd74 100644 --- a/build-tests/api-extractor-scenarios/src/readonlyDeclarations/index.ts +++ b/build-tests/api-extractor-scenarios/src/readonlyDeclarations/index.ts @@ -6,6 +6,11 @@ export interface _IInternalThing { title: string; } +/** @public */ +export const enum ConstEnum { + Zero, + One = 1 +} /** @public */ export class MyClass { public get _writableThing(): _IInternalThing { diff --git a/common/reviews/api/api-extractor-model.api.md b/common/reviews/api/api-extractor-model.api.md index 1e9f41a4d23..0c70a4c233a 100644 --- a/common/reviews/api/api-extractor-model.api.md +++ b/common/reviews/api/api-extractor-model.api.md @@ -707,7 +707,7 @@ export interface IApiEnumMemberOptions extends IApiNameMixinOptions, IApiRelease } // @public -export interface IApiEnumOptions extends IApiItemContainerMixinOptions, IApiNameMixinOptions, IApiReleaseTagMixinOptions, IApiDeclaredItemOptions { +export interface IApiEnumOptions extends IApiItemContainerMixinOptions, IApiNameMixinOptions, IApiReleaseTagMixinOptions, IApiDeclaredItemOptions, IApiReadonlyMixinOptions { } // @public diff --git a/libraries/api-extractor-model/src/model/ApiEnum.ts b/libraries/api-extractor-model/src/model/ApiEnum.ts index 14675678135..a9b1ed11f16 100644 --- a/libraries/api-extractor-model/src/model/ApiEnum.ts +++ b/libraries/api-extractor-model/src/model/ApiEnum.ts @@ -13,6 +13,7 @@ import { ApiReleaseTagMixin, IApiReleaseTagMixinOptions } from '../mixins/ApiRel import { ApiItemContainerMixin, IApiItemContainerMixinOptions } from '../mixins/ApiItemContainerMixin'; import { ApiEnumMember } from './ApiEnumMember'; import { IApiNameMixinOptions, ApiNameMixin } from '../mixins/ApiNameMixin'; +import { IApiReadonlyMixinOptions, ApiReadonlyMixin } from '../mixins/ApiReadonlyMixin'; /** * Constructor options for {@link ApiEnum}. @@ -22,7 +23,8 @@ export interface IApiEnumOptions extends IApiItemContainerMixinOptions, IApiNameMixinOptions, IApiReleaseTagMixinOptions, - IApiDeclaredItemOptions {} + IApiDeclaredItemOptions, + IApiReadonlyMixinOptions {} /** * Represents a TypeScript enum declaration. @@ -44,7 +46,7 @@ export interface IApiEnumOptions * * @public */ -export class ApiEnum extends ApiItemContainerMixin(ApiNameMixin(ApiReleaseTagMixin(ApiDeclaredItem))) { +export class ApiEnum extends ApiReadonlyMixin(ApiItemContainerMixin(ApiNameMixin(ApiReleaseTagMixin(ApiDeclaredItem)))) { public constructor(options: IApiEnumOptions) { super(options); } From e1ef04a788d012506fe343481b12354d46661c87 Mon Sep 17 00:00:00 2001 From: mrshllstock Date: Sun, 22 May 2022 14:28:27 -0700 Subject: [PATCH 04/14] [api-extractor] Apply readonly mixin to varaibles --- .../src/generators/ApiModelGenerator.ts | 7 ++- .../etc/api-documenter-test.api.json | 3 + .../api-extractor-scenarios.api.json | 3 + .../api-extractor-scenarios.api.json | 1 + .../api-extractor-scenarios.api.json | 1 + .../api-extractor-scenarios.api.json | 1 + .../api-extractor-scenarios.api.json | 2 + .../api-extractor-scenarios.api.json | 58 +++---------------- .../api-extractor-scenarios.api.md | 7 +-- .../readonlyDeclarations/rollup.d.ts | 5 +- .../api-extractor-scenarios.api.json | 1 + .../src/readonlyDeclarations/index.ts | 6 +- common/reviews/api/api-extractor-model.api.md | 2 +- .../src/model/ApiVariable.ts | 6 +- 14 files changed, 35 insertions(+), 68 deletions(-) diff --git a/apps/api-extractor/src/generators/ApiModelGenerator.ts b/apps/api-extractor/src/generators/ApiModelGenerator.ts index 611b3470155..ec71f2578fc 100644 --- a/apps/api-extractor/src/generators/ApiModelGenerator.ts +++ b/apps/api-extractor/src/generators/ApiModelGenerator.ts @@ -977,8 +977,9 @@ export class ApiModelGenerator { const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration); const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment; const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag; + const isReadonly: boolean = this._determineReadonly(astDeclaration); - apiVariable = new ApiVariable({ name, docComment, releaseTag, excerptTokens, variableTypeTokenRange }); + apiVariable = new ApiVariable({ name, docComment, releaseTag, excerptTokens, variableTypeTokenRange, isReadonly }); parentApiItem.addMember(apiVariable); } @@ -1059,8 +1060,10 @@ export class ApiModelGenerator { //Line 1: sees whether the readonly or const modifiers present //Line 2: sees if the TSDoc comment for @readonly is present //Line 3: sees whether a getter is present for a property with no setter + //Line 4: sees if the var has a Const flag return (astDeclaration.modifierFlags & (ts.ModifierFlags.Readonly + ts.ModifierFlags.Const)) !== 0 || (docComment !== undefined && docComment.modifierTagSet.hasTagName('@readonly')) - || (declarationMetadata.ancillaryDeclarations.length === 0 && astDeclaration.declaration.kind === ts.SyntaxKind.GetAccessor); + || (declarationMetadata.ancillaryDeclarations.length === 0 && astDeclaration.declaration.kind === ts.SyntaxKind.GetAccessor) + || (ts.getCombinedNodeFlags(astDeclaration.declaration) & ts.NodeFlags.Const) !== 0; } } diff --git a/build-tests/api-documenter-test/etc/api-documenter-test.api.json b/build-tests/api-documenter-test/etc/api-documenter-test.api.json index 66c12a36287..de32fe38cfc 100644 --- a/build-tests/api-documenter-test/etc/api-documenter-test.api.json +++ b/build-tests/api-documenter-test/etc/api-documenter-test.api.json @@ -211,6 +211,7 @@ ], "releaseTag": "Public", "name": "constVariable", + "isReadonly": true, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 @@ -1202,6 +1203,7 @@ ], "releaseTag": "Public", "name": "example", + "isReadonly": true, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 @@ -2439,6 +2441,7 @@ ], "releaseTag": "Public", "name": "nestedVariable", + "isReadonly": false, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json index 4ec3de2c917..1c4652e2cdb 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json @@ -469,6 +469,7 @@ ], "releaseTag": "Public", "name": "constVariable", + "isReadonly": false, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 @@ -490,6 +491,7 @@ ], "releaseTag": "Public", "name": "variable", + "isReadonly": false, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 @@ -745,6 +747,7 @@ ], "releaseTag": "Public", "name": "VARIABLE", + "isReadonly": true, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/defaultExportOfEntryPoint2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/defaultExportOfEntryPoint2/api-extractor-scenarios.api.json index 76b523e2f37..db974e045b2 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/defaultExportOfEntryPoint2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/defaultExportOfEntryPoint2/api-extractor-scenarios.api.json @@ -186,6 +186,7 @@ ], "releaseTag": "Public", "name": "defaultFunctionStatement", + "isReadonly": true, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/defaultExportOfEntryPoint4/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/defaultExportOfEntryPoint4/api-extractor-scenarios.api.json index 6adb6934b1f..32d3fb2740d 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/defaultExportOfEntryPoint4/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/defaultExportOfEntryPoint4/api-extractor-scenarios.api.json @@ -186,6 +186,7 @@ ], "releaseTag": "Public", "name": "_default", + "isReadonly": true, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/excerptTokens/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/excerptTokens/api-extractor-scenarios.api.json index 5900124b30c..c1890541e54 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/excerptTokens/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/excerptTokens/api-extractor-scenarios.api.json @@ -186,6 +186,7 @@ ], "releaseTag": "Public", "name": "MY_CONSTANT", + "isReadonly": false, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/exportImportStarAs/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/exportImportStarAs/api-extractor-scenarios.api.json index 9f78eeb5de8..0d4cfc68f73 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/exportImportStarAs/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/exportImportStarAs/api-extractor-scenarios.api.json @@ -254,6 +254,7 @@ ], "releaseTag": "Public", "name": "calucatorVersion", + "isReadonly": true, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 @@ -405,6 +406,7 @@ ], "releaseTag": "Public", "name": "calucatorVersion", + "isReadonly": true, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json index 8a0580a8789..9f6563394b1 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json @@ -214,62 +214,22 @@ "extendsTokenRanges": [] }, { - "kind": "Enum", - "canonicalReference": "api-extractor-scenarios!ConstEnum:enum", + "kind": "Variable", + "canonicalReference": "api-extractor-scenarios!FOO:var", "docComment": "/**\n * @public\n */\n", "excerptTokens": [ { "kind": "Content", - "text": "export declare const enum ConstEnum " + "text": "FOO = \"foo\"" } ], "releaseTag": "Public", - "name": "ConstEnum", - "members": [ - { - "kind": "EnumMember", - "canonicalReference": "api-extractor-scenarios!ConstEnum.One:member", - "docComment": "", - "excerptTokens": [ - { - "kind": "Content", - "text": "One = " - }, - { - "kind": "Content", - "text": "1" - } - ], - "releaseTag": "Public", - "name": "One", - "initializerTokenRange": { - "startIndex": 1, - "endIndex": 2 - } - }, - { - "kind": "EnumMember", - "canonicalReference": "api-extractor-scenarios!ConstEnum.Zero:member", - "docComment": "", - "excerptTokens": [ - { - "kind": "Content", - "text": "Zero = " - }, - { - "kind": "Content", - "text": "0" - } - ], - "releaseTag": "Public", - "name": "Zero", - "initializerTokenRange": { - "startIndex": 1, - "endIndex": 2 - } - } - ], - "isReadonly": true + "name": "FOO", + "isReadonly": true, + "variableTypeTokenRange": { + "startIndex": 0, + "endIndex": 0 + } }, { "kind": "Class", diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.md b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.md index 4f59fe5f876..c2da0080e20 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.md +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.md @@ -5,12 +5,7 @@ ```ts // @public (undocumented) -export const enum ConstEnum { - // (undocumented) - One = 1, - // (undocumented) - Zero = 0 -} +export const FOO = "foo"; // @public (undocumented) export interface _IInternalThing { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/rollup.d.ts index bda05b2d2ef..55210491872 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/rollup.d.ts +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/rollup.d.ts @@ -1,8 +1,5 @@ /** @public */ -export declare const enum ConstEnum { - Zero = 0, - One = 1 -} +export declare const FOO = "foo"; /** @public */ export declare interface _IInternalThing { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/api-extractor-scenarios.api.json index 2f3ce98bb78..5319a6b58a3 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/api-extractor-scenarios.api.json @@ -374,6 +374,7 @@ ], "releaseTag": "Public", "name": "exampleD", + "isReadonly": true, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 diff --git a/build-tests/api-extractor-scenarios/src/readonlyDeclarations/index.ts b/build-tests/api-extractor-scenarios/src/readonlyDeclarations/index.ts index 816f9f2dd74..fbd233d382f 100644 --- a/build-tests/api-extractor-scenarios/src/readonlyDeclarations/index.ts +++ b/build-tests/api-extractor-scenarios/src/readonlyDeclarations/index.ts @@ -7,10 +7,8 @@ export interface _IInternalThing { } /** @public */ -export const enum ConstEnum { - Zero, - One = 1 -} +export const FOO = 'foo'; + /** @public */ export class MyClass { public get _writableThing(): _IInternalThing { diff --git a/common/reviews/api/api-extractor-model.api.md b/common/reviews/api/api-extractor-model.api.md index 0c70a4c233a..24c8c02f623 100644 --- a/common/reviews/api/api-extractor-model.api.md +++ b/common/reviews/api/api-extractor-model.api.md @@ -854,7 +854,7 @@ export interface IApiTypeParameterOptions { } // @public -export interface IApiVariableOptions extends IApiNameMixinOptions, IApiReleaseTagMixinOptions, IApiDeclaredItemOptions { +export interface IApiVariableOptions extends IApiNameMixinOptions, IApiReleaseTagMixinOptions, IApiDeclaredItemOptions, IApiReadonlyMixinOptions { // (undocumented) variableTypeTokenRange: IExcerptTokenRange; } diff --git a/libraries/api-extractor-model/src/model/ApiVariable.ts b/libraries/api-extractor-model/src/model/ApiVariable.ts index 85cfef5e558..00eaed12838 100644 --- a/libraries/api-extractor-model/src/model/ApiVariable.ts +++ b/libraries/api-extractor-model/src/model/ApiVariable.ts @@ -10,6 +10,7 @@ import { import { ApiItemKind } from '../items/ApiItem'; import { ApiDeclaredItem, IApiDeclaredItemOptions, IApiDeclaredItemJson } from '../items/ApiDeclaredItem'; import { ApiReleaseTagMixin, IApiReleaseTagMixinOptions } from '../mixins/ApiReleaseTagMixin'; +import { ApiReadonlyMixin, IApiReadonlyMixinOptions } from '../mixins/ApiReadonlyMixin'; import { IApiNameMixinOptions, ApiNameMixin } from '../mixins/ApiNameMixin'; import { IExcerptTokenRange, Excerpt } from '../mixins/Excerpt'; import { DeserializerContext } from './DeserializerContext'; @@ -21,7 +22,8 @@ import { DeserializerContext } from './DeserializerContext'; export interface IApiVariableOptions extends IApiNameMixinOptions, IApiReleaseTagMixinOptions, - IApiDeclaredItemOptions { + IApiDeclaredItemOptions, + IApiReadonlyMixinOptions { variableTypeTokenRange: IExcerptTokenRange; } @@ -49,7 +51,7 @@ export interface IApiVariableJson extends IApiDeclaredItemJson { * * @public */ -export class ApiVariable extends ApiNameMixin(ApiReleaseTagMixin(ApiDeclaredItem)) { +export class ApiVariable extends ApiReadonlyMixin(ApiNameMixin(ApiReleaseTagMixin(ApiDeclaredItem))) { /** * An {@link Excerpt} that describes the type of the variable. */ From b6448b6888c5013de7612f8a7b658bfe40d81f6c Mon Sep 17 00:00:00 2001 From: mrshllstock Date: Mon, 23 May 2022 09:31:51 -0700 Subject: [PATCH 05/14] [api-extractor] include ts.isVarConst to typescript internals --- apps/api-extractor/src/analyzer/TypeScriptInternals.ts | 8 ++++++++ apps/api-extractor/src/generators/ApiModelGenerator.ts | 4 +++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/apps/api-extractor/src/analyzer/TypeScriptInternals.ts b/apps/api-extractor/src/analyzer/TypeScriptInternals.ts index 4c35cc1ded9..a60598b6183 100644 --- a/apps/api-extractor/src/analyzer/TypeScriptInternals.ts +++ b/apps/api-extractor/src/analyzer/TypeScriptInternals.ts @@ -124,4 +124,12 @@ export class TypeScriptInternals { } return resolver; } + + /** + * Returns whether a variable has the const declaration + */ + public static isVarConst(node: ts.VariableDeclaration | ts.VariableDeclarationList): boolean { + // Compiler internal: https://github.com/microsoft/TypeScript/blob/71286e3d49c10e0e99faac360a6bbd40f12db7b6/src/compiler/utilities.ts#L925 + return (ts as any).isVarConst(node); + } } diff --git a/apps/api-extractor/src/generators/ApiModelGenerator.ts b/apps/api-extractor/src/generators/ApiModelGenerator.ts index ec71f2578fc..dd59c79283a 100644 --- a/apps/api-extractor/src/generators/ApiModelGenerator.ts +++ b/apps/api-extractor/src/generators/ApiModelGenerator.ts @@ -44,6 +44,8 @@ import { AstNamespaceImport } from '../analyzer/AstNamespaceImport'; import { AstEntity } from '../analyzer/AstEntity'; import { AstModule } from '../analyzer/AstModule'; +import { TypeScriptInternals } from '../analyzer/TypeScriptInternals'; + export class ApiModelGenerator { private readonly _collector: Collector; private readonly _apiModel: ApiModel; @@ -1064,6 +1066,6 @@ export class ApiModelGenerator { return (astDeclaration.modifierFlags & (ts.ModifierFlags.Readonly + ts.ModifierFlags.Const)) !== 0 || (docComment !== undefined && docComment.modifierTagSet.hasTagName('@readonly')) || (declarationMetadata.ancillaryDeclarations.length === 0 && astDeclaration.declaration.kind === ts.SyntaxKind.GetAccessor) - || (ts.getCombinedNodeFlags(astDeclaration.declaration) & ts.NodeFlags.Const) !== 0; + || ts.isVariableDeclaration(astDeclaration.declaration) && TypeScriptInternals.isVarConst(astDeclaration.declaration) } } From b9d1d35adccf4637e775fc666a1f75aef7ad1218 Mon Sep 17 00:00:00 2001 From: mrshllstock Date: Mon, 23 May 2022 12:25:55 -0700 Subject: [PATCH 06/14] [api-extractor] address comments --- .../src/analyzer/TypeScriptInternals.ts | 2 +- .../src/generators/ApiModelGenerator.ts | 15 +++++---------- .../etc/api-documenter-test.api.json | 18 ++---------------- .../api-extractor-scenarios.api.json | 11 ++--------- .../api-extractor-scenarios.api.json | 1 - .../api-extractor-scenarios.api.json | 6 ------ .../api-extractor-scenarios.api.json | 1 - .../api-extractor-scenarios.api.json | 1 - .../api-extractor-scenarios.api.json | 2 -- .../api-extractor-scenarios.api.json | 3 --- .../api-extractor-scenarios.api.json | 3 --- .../api-extractor-scenarios.api.json | 1 - common/reviews/api/api-extractor-model.api.md | 6 +++--- .../api-extractor-model/src/model/ApiEnum.ts | 6 ++---- .../api-extractor-model/src/model/ApiMethod.ts | 6 +----- .../src/model/ApiMethodSignature.ts | 6 +----- 16 files changed, 17 insertions(+), 71 deletions(-) diff --git a/apps/api-extractor/src/analyzer/TypeScriptInternals.ts b/apps/api-extractor/src/analyzer/TypeScriptInternals.ts index a60598b6183..cf4615fe1ff 100644 --- a/apps/api-extractor/src/analyzer/TypeScriptInternals.ts +++ b/apps/api-extractor/src/analyzer/TypeScriptInternals.ts @@ -126,7 +126,7 @@ export class TypeScriptInternals { } /** - * Returns whether a variable has the const declaration + * Returns whether a variable is declared with the const keyword */ public static isVarConst(node: ts.VariableDeclaration | ts.VariableDeclarationList): boolean { // Compiler internal: https://github.com/microsoft/TypeScript/blob/71286e3d49c10e0e99faac360a6bbd40f12db7b6/src/compiler/utilities.ts#L925 diff --git a/apps/api-extractor/src/generators/ApiModelGenerator.ts b/apps/api-extractor/src/generators/ApiModelGenerator.ts index dd59c79283a..6b734f50f79 100644 --- a/apps/api-extractor/src/generators/ApiModelGenerator.ts +++ b/apps/api-extractor/src/generators/ApiModelGenerator.ts @@ -473,9 +473,8 @@ export class ApiModelGenerator { const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration); const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment; const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag; - const isReadonly: boolean = this._determineReadonly(astDeclaration); - apiEnum = new ApiEnum({ name, docComment, releaseTag, excerptTokens, isReadonly }); + apiEnum = new ApiEnum({ name, docComment, releaseTag, excerptTokens }); parentApiItem.addMember(apiEnum); } @@ -712,7 +711,6 @@ export class ApiModelGenerator { } const isOptional: boolean = (astDeclaration.astSymbol.followedSymbol.flags & ts.SymbolFlags.Optional) !== 0; - const isReadonly: boolean = this._determineReadonly(astDeclaration); apiMethod = new ApiMethod({ name, @@ -724,8 +722,7 @@ export class ApiModelGenerator { parameters, overloadIndex, excerptTokens, - returnTypeTokenRange, - isReadonly + returnTypeTokenRange }); parentApiItem.addMember(apiMethod); @@ -770,7 +767,6 @@ export class ApiModelGenerator { const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag; const isOptional: boolean = (astDeclaration.astSymbol.followedSymbol.flags & ts.SymbolFlags.Optional) !== 0; - const isReadonly: boolean = this._determineReadonly(astDeclaration); apiMethodSignature = new ApiMethodSignature({ name, @@ -781,8 +777,7 @@ export class ApiModelGenerator { parameters, overloadIndex, excerptTokens, - returnTypeTokenRange, - isReadonly + returnTypeTokenRange }); parentApiItem.addMember(apiMethodSignature); @@ -1059,10 +1054,10 @@ export class ApiModelGenerator { const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration); const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment; const declarationMetadata: DeclarationMetadata = this._collector.fetchDeclarationMetadata(astDeclaration); - //Line 1: sees whether the readonly or const modifiers present + //Line 1: sees whether the readonly or const modifiers are present //Line 2: sees if the TSDoc comment for @readonly is present //Line 3: sees whether a getter is present for a property with no setter - //Line 4: sees if the var has a Const flag + //Line 4: sees if the var declaration has Const keyword return (astDeclaration.modifierFlags & (ts.ModifierFlags.Readonly + ts.ModifierFlags.Const)) !== 0 || (docComment !== undefined && docComment.modifierTagSet.hasTagName('@readonly')) || (declarationMetadata.ancillaryDeclarations.length === 0 && astDeclaration.declaration.kind === ts.SyntaxKind.GetAccessor) diff --git a/build-tests/api-documenter-test/etc/api-documenter-test.api.json b/build-tests/api-documenter-test/etc/api-documenter-test.api.json index de32fe38cfc..370f707dc71 100644 --- a/build-tests/api-documenter-test/etc/api-documenter-test.api.json +++ b/build-tests/api-documenter-test/etc/api-documenter-test.api.json @@ -400,7 +400,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -446,7 +445,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -501,7 +499,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -570,7 +567,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -622,7 +618,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -718,7 +713,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -830,7 +824,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": true, "returnTypeTokenRange": { @@ -877,7 +870,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -1071,8 +1063,7 @@ "endIndex": 2 } } - ], - "isReadonly": false + ] }, { "kind": "Enum", @@ -1129,8 +1120,7 @@ "endIndex": 2 } } - ], - "isReadonly": false + ] }, { "kind": "Namespace", @@ -1523,7 +1513,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "returnTypeTokenRange": { "startIndex": 1, @@ -2004,7 +1993,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "returnTypeTokenRange": { "startIndex": 3, @@ -2285,7 +2273,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": true, "returnTypeTokenRange": { "startIndex": 1, @@ -2488,7 +2475,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json index 1c4652e2cdb..795b7931537 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json @@ -201,7 +201,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -255,7 +254,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -303,7 +301,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -394,8 +391,7 @@ "endIndex": 2 } } - ], - "isReadonly": true + ] }, { "kind": "Interface", @@ -575,8 +571,7 @@ "endIndex": 2 } } - ], - "isReadonly": false + ] }, { "kind": "Class", @@ -609,7 +604,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -647,7 +641,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.json index c42c2c71301..70a404789c6 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.json @@ -276,7 +276,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/api-extractor-scenarios.api.json index 84f26614b33..80a235676d1 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/api-extractor-scenarios.api.json @@ -201,7 +201,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -231,7 +230,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -277,7 +275,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -307,7 +304,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -353,7 +349,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -383,7 +378,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json index 3cb7f34446f..daf4083bdeb 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json @@ -257,7 +257,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/excerptTokens/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/excerptTokens/api-extractor-scenarios.api.json index c1890541e54..eee65272256 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/excerptTokens/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/excerptTokens/api-extractor-scenarios.api.json @@ -239,7 +239,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/functionOverload/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/functionOverload/api-extractor-scenarios.api.json index c8a2b46ec96..ddb53fa73eb 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/functionOverload/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/functionOverload/api-extractor-scenarios.api.json @@ -397,7 +397,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -460,7 +459,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/internationalCharacters/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/internationalCharacters/api-extractor-scenarios.api.json index 61146f83b48..1d9fd5abb8f 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/internationalCharacters/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/internationalCharacters/api-extractor-scenarios.api.json @@ -210,7 +210,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -262,7 +261,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -301,7 +299,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/api-extractor-scenarios.api.json index 5319a6b58a3..dac8f533977 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/api-extractor-scenarios.api.json @@ -234,7 +234,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -288,7 +287,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { @@ -343,7 +341,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/typeParameters/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/typeParameters/api-extractor-scenarios.api.json index a0055cdc109..9ec55e71032 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/typeParameters/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/typeParameters/api-extractor-scenarios.api.json @@ -201,7 +201,6 @@ "text": ";" } ], - "isReadonly": false, "isOptional": false, "isStatic": false, "returnTypeTokenRange": { diff --git a/common/reviews/api/api-extractor-model.api.md b/common/reviews/api/api-extractor-model.api.md index 24c8c02f623..8c89cab6e4f 100644 --- a/common/reviews/api/api-extractor-model.api.md +++ b/common/reviews/api/api-extractor-model.api.md @@ -707,7 +707,7 @@ export interface IApiEnumMemberOptions extends IApiNameMixinOptions, IApiRelease } // @public -export interface IApiEnumOptions extends IApiItemContainerMixinOptions, IApiNameMixinOptions, IApiReleaseTagMixinOptions, IApiDeclaredItemOptions, IApiReadonlyMixinOptions { +export interface IApiEnumOptions extends IApiItemContainerMixinOptions, IApiNameMixinOptions, IApiReleaseTagMixinOptions, IApiDeclaredItemOptions { } // @public @@ -739,11 +739,11 @@ export interface IApiItemOptions { } // @public -export interface IApiMethodOptions extends IApiNameMixinOptions, IApiTypeParameterListMixinOptions, IApiParameterListMixinOptions, IApiReleaseTagMixinOptions, IApiReturnTypeMixinOptions, IApiStaticMixinOptions, IApiOptionalMixinOptions, IApiReadonlyMixinOptions, IApiDeclaredItemOptions { +export interface IApiMethodOptions extends IApiNameMixinOptions, IApiTypeParameterListMixinOptions, IApiParameterListMixinOptions, IApiReleaseTagMixinOptions, IApiReturnTypeMixinOptions, IApiStaticMixinOptions, IApiOptionalMixinOptions, IApiDeclaredItemOptions { } // @public (undocumented) -export interface IApiMethodSignatureOptions extends IApiNameMixinOptions, IApiTypeParameterListMixinOptions, IApiParameterListMixinOptions, IApiReleaseTagMixinOptions, IApiReturnTypeMixinOptions, IApiOptionalMixinOptions, IApiReadonlyMixinOptions, IApiDeclaredItemOptions { +export interface IApiMethodSignatureOptions extends IApiNameMixinOptions, IApiTypeParameterListMixinOptions, IApiParameterListMixinOptions, IApiReleaseTagMixinOptions, IApiReturnTypeMixinOptions, IApiOptionalMixinOptions, IApiDeclaredItemOptions { } // @public diff --git a/libraries/api-extractor-model/src/model/ApiEnum.ts b/libraries/api-extractor-model/src/model/ApiEnum.ts index a9b1ed11f16..14675678135 100644 --- a/libraries/api-extractor-model/src/model/ApiEnum.ts +++ b/libraries/api-extractor-model/src/model/ApiEnum.ts @@ -13,7 +13,6 @@ import { ApiReleaseTagMixin, IApiReleaseTagMixinOptions } from '../mixins/ApiRel import { ApiItemContainerMixin, IApiItemContainerMixinOptions } from '../mixins/ApiItemContainerMixin'; import { ApiEnumMember } from './ApiEnumMember'; import { IApiNameMixinOptions, ApiNameMixin } from '../mixins/ApiNameMixin'; -import { IApiReadonlyMixinOptions, ApiReadonlyMixin } from '../mixins/ApiReadonlyMixin'; /** * Constructor options for {@link ApiEnum}. @@ -23,8 +22,7 @@ export interface IApiEnumOptions extends IApiItemContainerMixinOptions, IApiNameMixinOptions, IApiReleaseTagMixinOptions, - IApiDeclaredItemOptions, - IApiReadonlyMixinOptions {} + IApiDeclaredItemOptions {} /** * Represents a TypeScript enum declaration. @@ -46,7 +44,7 @@ export interface IApiEnumOptions * * @public */ -export class ApiEnum extends ApiReadonlyMixin(ApiItemContainerMixin(ApiNameMixin(ApiReleaseTagMixin(ApiDeclaredItem)))) { +export class ApiEnum extends ApiItemContainerMixin(ApiNameMixin(ApiReleaseTagMixin(ApiDeclaredItem))) { public constructor(options: IApiEnumOptions) { super(options); } diff --git a/libraries/api-extractor-model/src/model/ApiMethod.ts b/libraries/api-extractor-model/src/model/ApiMethod.ts index 567a5e362de..fbfe2c4a8e2 100644 --- a/libraries/api-extractor-model/src/model/ApiMethod.ts +++ b/libraries/api-extractor-model/src/model/ApiMethod.ts @@ -19,7 +19,6 @@ import { IApiTypeParameterListMixinOptions } from '../mixins/ApiTypeParameterListMixin'; import { ApiOptionalMixin, IApiOptionalMixinOptions } from '../mixins/ApiOptionalMixin'; -import { ApiReadonlyMixin, IApiReadonlyMixinOptions } from '../mixins/ApiReadonlyMixin'; /** * Constructor options for {@link ApiMethod}. @@ -33,7 +32,6 @@ export interface IApiMethodOptions IApiReturnTypeMixinOptions, IApiStaticMixinOptions, IApiOptionalMixinOptions, - IApiReadonlyMixinOptions, IApiDeclaredItemOptions {} /** @@ -60,9 +58,7 @@ export interface IApiMethodOptions export class ApiMethod extends ApiNameMixin( ApiTypeParameterListMixin( ApiParameterListMixin( - ApiReleaseTagMixin( - ApiReturnTypeMixin(ApiStaticMixin(ApiOptionalMixin(ApiReadonlyMixin(ApiDeclaredItem)))) - ) + ApiReleaseTagMixin(ApiReturnTypeMixin(ApiStaticMixin(ApiOptionalMixin(ApiDeclaredItem)))) ) ) ) { diff --git a/libraries/api-extractor-model/src/model/ApiMethodSignature.ts b/libraries/api-extractor-model/src/model/ApiMethodSignature.ts index b7a56aa7a94..caf8541b028 100644 --- a/libraries/api-extractor-model/src/model/ApiMethodSignature.ts +++ b/libraries/api-extractor-model/src/model/ApiMethodSignature.ts @@ -18,7 +18,6 @@ import { ApiTypeParameterListMixin } from '../mixins/ApiTypeParameterListMixin'; import { ApiOptionalMixin, IApiOptionalMixinOptions } from '../mixins/ApiOptionalMixin'; -import { ApiReadonlyMixin, IApiReadonlyMixinOptions } from '../mixins/ApiReadonlyMixin'; /** @public */ export interface IApiMethodSignatureOptions @@ -28,7 +27,6 @@ export interface IApiMethodSignatureOptions IApiReleaseTagMixinOptions, IApiReturnTypeMixinOptions, IApiOptionalMixinOptions, - IApiReadonlyMixinOptions, IApiDeclaredItemOptions {} /** @@ -54,9 +52,7 @@ export interface IApiMethodSignatureOptions */ export class ApiMethodSignature extends ApiNameMixin( ApiTypeParameterListMixin( - ApiParameterListMixin( - ApiReleaseTagMixin(ApiReturnTypeMixin(ApiOptionalMixin(ApiReadonlyMixin(ApiDeclaredItem)))) - ) + ApiParameterListMixin(ApiReleaseTagMixin(ApiReturnTypeMixin(ApiOptionalMixin(ApiDeclaredItem)))) ) ) { public constructor(options: IApiMethodSignatureOptions) { From 48e4046a812074d97d80d779fda20133de8c380c Mon Sep 17 00:00:00 2001 From: mrshllstock Date: Mon, 23 May 2022 13:05:17 -0700 Subject: [PATCH 07/14] [api-extractor] cleanup and verify static readonly case --- .../etc/api-documenter-test.api.json | 28 +++++++++++++++++++ .../etc/api-documenter-test.api.md | 2 ++ .../markdown/api-documenter-test.docclass1.md | 1 + ...nter-test.docclass1.staticreadonlything.md | 11 ++++++++ .../yaml/api-documenter-test/docclass1.yml | 13 +++++++++ .../api-documenter-test/src/DocClass1.ts | 2 ++ .../api-extractor-scenarios.api.json | 6 ++-- .../api-extractor-scenarios.api.md | 2 +- .../readonlyDeclarations/rollup.d.ts | 2 +- .../src/readonlyDeclarations/index.ts | 2 +- 10 files changed, 63 insertions(+), 6 deletions(-) create mode 100644 build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.staticreadonlything.md diff --git a/build-tests/api-documenter-test/etc/api-documenter-test.api.json b/build-tests/api-documenter-test/etc/api-documenter-test.api.json index 370f707dc71..7ff939b6140 100644 --- a/build-tests/api-documenter-test/etc/api-documenter-test.api.json +++ b/build-tests/api-documenter-test/etc/api-documenter-test.api.json @@ -790,6 +790,34 @@ }, "isStatic": false }, + { + "kind": "Property", + "canonicalReference": "api-documenter-test!DocClass1.staticReadonlyThing:member", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "static readonly staticReadonlyThing: " + }, + { + "kind": "Content", + "text": "boolean" + }, + { + "kind": "Content", + "text": ";" + } + ], + "isReadonly": true, + "isOptional": false, + "releaseTag": "Public", + "name": "staticReadonlyThing", + "propertyTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "isStatic": true + }, { "kind": "Method", "canonicalReference": "api-documenter-test!DocClass1.sumWithExample:member(1)", diff --git a/build-tests/api-documenter-test/etc/api-documenter-test.api.md b/build-tests/api-documenter-test/etc/api-documenter-test.api.md index 828c30e2583..e9e1412b999 100644 --- a/build-tests/api-documenter-test/etc/api-documenter-test.api.md +++ b/build-tests/api-documenter-test/etc/api-documenter-test.api.md @@ -44,6 +44,8 @@ export class DocClass1 extends DocBaseClass implements IDocInterface1, IDocInter // (undocumented) get readonlyProperty(): string; regularProperty: SystemEvent; + // (undocumented) + static readonly staticReadonlyThing: boolean; static sumWithExample(x: number, y: number): number; tableExample(): void; // (undocumented) diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md index 478eba2e035..f37f7abb0ff 100644 --- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md +++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md @@ -37,6 +37,7 @@ The constructor for this class is marked as internal. Third-party code should no | --- | --- | --- | --- | | [readonlyProperty](./api-documenter-test.docclass1.readonlyproperty.md) | readonly | string | | | [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. | +| [staticReadonlyThing](./api-documenter-test.docclass1.staticreadonlything.md) | staticreadonly | boolean | | | [writeableProperty](./api-documenter-test.docclass1.writeableproperty.md) | | string | | | [writeonlyProperty](./api-documenter-test.docclass1.writeonlyproperty.md) | | string | API Extractor will surface an ae-missing-getter finding for this property. | diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.staticreadonlything.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.staticreadonlything.md new file mode 100644 index 00000000000..ecb46a0668b --- /dev/null +++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.staticreadonlything.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [api-documenter-test](./api-documenter-test.md) > [DocClass1](./api-documenter-test.docclass1.md) > [staticReadonlyThing](./api-documenter-test.docclass1.staticreadonlything.md) + +## DocClass1.staticReadonlyThing property + +Signature: + +```typescript +static readonly staticReadonlyThing: boolean; +``` diff --git a/build-tests/api-documenter-test/etc/yaml/api-documenter-test/docclass1.yml b/build-tests/api-documenter-test/etc/yaml/api-documenter-test/docclass1.yml index b02c6cb4ff3..5914b86ab2b 100644 --- a/build-tests/api-documenter-test/etc/yaml/api-documenter-test/docclass1.yml +++ b/build-tests/api-documenter-test/etc/yaml/api-documenter-test/docclass1.yml @@ -45,6 +45,19 @@ properties: content: 'regularProperty: SystemEvent;' return: type: '' + - name: staticReadonlyThing + uid: 'api-documenter-test!DocClass1.staticReadonlyThing:member' + package: api-documenter-test! + fullName: staticReadonlyThing + summary: '' + remarks: '' + example: [] + isPreview: false + isDeprecated: false + syntax: + content: 'static readonly staticReadonlyThing: boolean;' + return: + type: boolean - name: writeableProperty uid: 'api-documenter-test!DocClass1#writeableProperty:member' package: api-documenter-test! diff --git a/build-tests/api-documenter-test/src/DocClass1.ts b/build-tests/api-documenter-test/src/DocClass1.ts index 313a0f45a95..08c5764ca10 100644 --- a/build-tests/api-documenter-test/src/DocClass1.ts +++ b/build-tests/api-documenter-test/src/DocClass1.ts @@ -169,6 +169,8 @@ export class DocClass1 extends DocBaseClass implements IDocInterface1, IDocInter super(); } + static readonly staticReadonlyThing: boolean; + /** * This is an overloaded function. * @param a - the first string diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json index 9f6563394b1..c8733be5632 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json @@ -317,12 +317,12 @@ }, { "kind": "Property", - "canonicalReference": "api-extractor-scenarios!MyClass#declaredReadonlyThing:member", + "canonicalReference": "api-extractor-scenarios!MyClass.declaredReadonlyThing:member", "docComment": "", "excerptTokens": [ { "kind": "Content", - "text": "readonly declaredReadonlyThing: " + "text": "static readonly declaredReadonlyThing: " }, { "kind": "Reference", @@ -342,7 +342,7 @@ "startIndex": 1, "endIndex": 2 }, - "isStatic": false + "isStatic": true }, { "kind": "Property", diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.md b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.md index c2da0080e20..a3b886324d9 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.md +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.md @@ -16,7 +16,7 @@ export interface _IInternalThing { // @public (undocumented) export class MyClass { // (undocumented) - readonly declaredReadonlyThing: _IInternalThing; + static readonly declaredReadonlyThing: _IInternalThing; // (undocumented) get _onlyHasGetterThing(): _IInternalThing; tsDocReadonlyThing: _IInternalThing; diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/rollup.d.ts index 55210491872..d133028f380 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/rollup.d.ts +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/rollup.d.ts @@ -11,7 +11,7 @@ export declare class MyClass { get _writableThing(): _IInternalThing; set _writableThing(value: _IInternalThing); get _onlyHasGetterThing(): _IInternalThing; - readonly declaredReadonlyThing: _IInternalThing; + static readonly declaredReadonlyThing: _IInternalThing; /** * Technically isn't but for testing purposes * @readonly diff --git a/build-tests/api-extractor-scenarios/src/readonlyDeclarations/index.ts b/build-tests/api-extractor-scenarios/src/readonlyDeclarations/index.ts index fbd233d382f..9d627cc9b4c 100644 --- a/build-tests/api-extractor-scenarios/src/readonlyDeclarations/index.ts +++ b/build-tests/api-extractor-scenarios/src/readonlyDeclarations/index.ts @@ -21,7 +21,7 @@ export class MyClass { return { title: 'thing' }; } - readonly declaredReadonlyThing: _IInternalThing; + static readonly declaredReadonlyThing: _IInternalThing; /** * Technically isn't but for testing purposes From a41f3fa5a285fbda1fe7cb4a6adb925dea370de5 Mon Sep 17 00:00:00 2001 From: mrshllstock Date: Mon, 6 Jun 2022 14:25:20 -0700 Subject: [PATCH 08/14] remove readonly from markdown report for future bug fix --- .../src/documenters/MarkdownDocumenter.ts | 9 +------- .../markdown/api-documenter-test.docclass1.md | 6 ++--- .../workspace/common/pnpm-lock.yaml | 22 +++++++++---------- .../api-readonly-mixin_2022-05-19-20-18.json | 10 --------- 4 files changed, 15 insertions(+), 32 deletions(-) delete mode 100644 common/changes/@microsoft/api-documenter/api-readonly-mixin_2022-05-19-20-18.json diff --git a/apps/api-documenter/src/documenters/MarkdownDocumenter.ts b/apps/api-documenter/src/documenters/MarkdownDocumenter.ts index 4c0c1378f16..8fbf10db3a5 100644 --- a/apps/api-documenter/src/documenters/MarkdownDocumenter.ts +++ b/apps/api-documenter/src/documenters/MarkdownDocumenter.ts @@ -40,8 +40,7 @@ import { IResolveDeclarationReferenceResult, ApiTypeAlias, ExcerptToken, - ApiOptionalMixin, - ApiReadonlyMixin + ApiOptionalMixin } from '@microsoft/api-extractor-model'; import { CustomDocNodes } from '../nodes/CustomDocNodeKind'; @@ -1019,12 +1018,6 @@ export class MarkdownDocumenter { } } - if (ApiReadonlyMixin.isBaseClassOf(apiItem)) { - if (apiItem.isReadonly) { - section.appendNodeInParagraph(new DocCodeSpan({ configuration, code: 'readonly' })); - } - } - return new DocTableCell({ configuration }, section.nodes); } diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md index f37f7abb0ff..e6c3fa4b49d 100644 --- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md +++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md @@ -29,15 +29,15 @@ The constructor for this class is marked as internal. Third-party code should no | Property | Modifiers | Type | Description | | --- | --- | --- | --- | | [malformedEvent](./api-documenter-test.docclass1.malformedevent.md) | | [SystemEvent](./api-documenter-test.systemevent.md) | This event should have been marked as readonly. | -| [modifiedEvent](./api-documenter-test.docclass1.modifiedevent.md) | readonly | [SystemEvent](./api-documenter-test.systemevent.md) | This event is fired whenever the object is modified. | +| [modifiedEvent](./api-documenter-test.docclass1.modifiedevent.md) | | [SystemEvent](./api-documenter-test.systemevent.md) | This event is fired whenever the object is modified. | ## Properties | Property | Modifiers | Type | Description | | --- | --- | --- | --- | -| [readonlyProperty](./api-documenter-test.docclass1.readonlyproperty.md) | readonly | string | | +| [readonlyProperty](./api-documenter-test.docclass1.readonlyproperty.md) | | string | | | [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. | -| [staticReadonlyThing](./api-documenter-test.docclass1.staticreadonlything.md) | staticreadonly | boolean | | +| [staticReadonlyThing](./api-documenter-test.docclass1.staticreadonlything.md) | static | boolean | | | [writeableProperty](./api-documenter-test.docclass1.writeableproperty.md) | | string | | | [writeonlyProperty](./api-documenter-test.docclass1.writeonlyproperty.md) | | string | API Extractor will surface an ae-missing-getter finding for this property. | diff --git a/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml b/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml index b5d818de2b1..e423efe6c03 100644 --- a/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml +++ b/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml @@ -794,7 +794,7 @@ packages: dev: true /fs.realpath/1.0.0: - resolution: {integrity: sha1-FQStJSMVjKpA20onh8sBQRmU6k8=} + resolution: {integrity: sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==} dev: true /fsevents/2.1.3: @@ -831,7 +831,7 @@ packages: dev: true /glob-escape/0.0.2: - resolution: {integrity: sha1-nCf3gh7RwTd1gvPv2VWOP2dWKO0=} + resolution: {integrity: sha512-L/cXYz8x7qer1HAyUQ+mbjcUsJVdpRxpAf7CwqHoNBs9vTpABlGfNN4tzkDxt+u3Z7ZncVyKlCNPtzb0R/7WbA==} engines: {node: '>= 0.10'} dev: true @@ -850,7 +850,7 @@ packages: dev: true /glob/7.0.6: - resolution: {integrity: sha1-IRuvr0nlJbjNkyYNFKsTYVKz9Xo=} + resolution: {integrity: sha512-f8c0rE8JiCxpa52kWPAOa3ZaYEnzofDzCQLCn3Vdk0Z5OVLq3BsRFJI4S4ykpeVW6QMGBUkMeUpoEgWnMTnw5Q==} dependencies: fs.realpath: 1.0.0 inflight: 1.0.6 @@ -956,7 +956,7 @@ packages: dev: true /inflight/1.0.6: - resolution: {integrity: sha1-Sb1jMdfQLQwJvJEKEHW6gWW1bfk=} + resolution: {integrity: sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==} dependencies: once: 1.4.0 wrappy: 1.0.2 @@ -1073,7 +1073,7 @@ packages: dev: true /jju/1.4.0: - resolution: {integrity: sha1-o6vicYryQaKykE+EpiWXDzia4yo=} + resolution: {integrity: sha512-8wb9Yw966OSxApiCt0K3yNJL8pnNeIv+OEq2YMidz4FKP6nonSRoOXc80iXY4JaN2FC11B9qsNmDsm+ZOfMROA==} dev: true /js-tokens/4.0.0: @@ -1104,7 +1104,7 @@ packages: dev: true /jsonfile/4.0.0: - resolution: {integrity: sha1-h3Gq4HmbZAdrdmQPygWPnBDjPss=} + resolution: {integrity: sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==} optionalDependencies: graceful-fs: 4.2.6 dev: true @@ -1131,11 +1131,11 @@ packages: dev: true /lodash.get/4.4.2: - resolution: {integrity: sha1-LRd/ZS+jHpObRDjVNBSZ36OCXpk=} + resolution: {integrity: sha512-z+Uw/vLuy6gQe8cfaFWD7p0wVv8fJl3mbzXh33RS+0oW2wvUqiRXiQ69gLWSLpgB5/6sU+r6BlQR0MBILadqTQ==} dev: true /lodash.isequal/4.5.0: - resolution: {integrity: sha1-QVxEePK8wwEgwizhDtMib30+GOA=} + resolution: {integrity: sha512-pDo3lu8Jhfjqls6GkMgpahsF9kCyayhgykjyLMNFTKWrpVdAQtYyB4muAMWozBB4ig/dtWAmsMxLEI8wuz+DYQ==} dev: true /lodash.merge/4.6.2: @@ -1200,7 +1200,7 @@ packages: dev: true /object-assign/4.1.1: - resolution: {integrity: sha1-IQmtx5ZYh8/AXLvUQsrIv7s2CGM=} + resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==} engines: {node: '>=0.10.0'} dev: true @@ -1258,7 +1258,7 @@ packages: dev: true /once/1.4.0: - resolution: {integrity: sha1-WDsap3WWHUsROsF9nFC6753Xa9E=} + resolution: {integrity: sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==} dependencies: wrappy: 1.0.2 dev: true @@ -1283,7 +1283,7 @@ packages: dev: true /path-is-absolute/1.0.1: - resolution: {integrity: sha1-F0uSaHNVNP+8es5r9TpanhtcX18=} + resolution: {integrity: sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==} engines: {node: '>=0.10.0'} dev: true diff --git a/common/changes/@microsoft/api-documenter/api-readonly-mixin_2022-05-19-20-18.json b/common/changes/@microsoft/api-documenter/api-readonly-mixin_2022-05-19-20-18.json deleted file mode 100644 index 97364dbdff8..00000000000 --- a/common/changes/@microsoft/api-documenter/api-readonly-mixin_2022-05-19-20-18.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "changes": [ - { - "packageName": "@microsoft/api-documenter", - "comment": "Add support for rendering readonly information next to API items", - "type": "minor" - } - ], - "packageName": "@microsoft/api-documenter" -} \ No newline at end of file From 25235a213fe905c03e4883c8a47487fe88e568c1 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Tue, 7 Jun 2022 01:31:19 -0700 Subject: [PATCH 09/14] Include isReadonly in the ApiJsonSchemaVersion.V_1006 bump --- .../api-extractor-model/src/model/DeserializerContext.ts | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/libraries/api-extractor-model/src/model/DeserializerContext.ts b/libraries/api-extractor-model/src/model/DeserializerContext.ts index 12cd9e15514..07ea19ce36f 100644 --- a/libraries/api-extractor-model/src/model/DeserializerContext.ts +++ b/libraries/api-extractor-model/src/model/DeserializerContext.ts @@ -36,17 +36,20 @@ export enum ApiJsonSchemaVersion { V_1004 = 1004, /** - * Add an `isOptional` field to `IApiParameterOptions` to track whether a function parameter is optional. + * Add an `isOptional` field to `Parameter` and `TypeParameter` to track whether a function parameter is optional. * * When loading older JSON files, the value defaults to `false`. */ V_1005 = 1005, /** - * Add an `isProtected` field to `IApiConstructorOptions`, `IApiPropertyOptions`, and `IApiMethodOptions` to + * Add an `isProtected` field to `ApiConstructor`, `ApiMethod`, and `ApiProperty` to * track whether a class member has the `protected` modifier. * - * When loading older JSON files, the value defaults to `false`. + * Add an `isReadonly` field to `ApiProperty`, `ApiPropertySignature`, and `ApiVariable` to + * track whether the item is readonly. + * + * When loading older JSON files, the values default to `false`. */ V_1006 = 1006, From 5439ed1d5aa0868079345f7fe6c65dc12f03009a Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Tue, 7 Jun 2022 01:41:22 -0700 Subject: [PATCH 10/14] Remove ApiReadonlyMixin from ApiProperty and ApiPropertySignature because it is already inherited from ApiPropertyItem --- libraries/api-extractor-model/src/model/ApiProperty.ts | 4 +--- .../api-extractor-model/src/model/ApiPropertySignature.ts | 6 +++--- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/libraries/api-extractor-model/src/model/ApiProperty.ts b/libraries/api-extractor-model/src/model/ApiProperty.ts index 8d4896206e1..6739dce26fd 100644 --- a/libraries/api-extractor-model/src/model/ApiProperty.ts +++ b/libraries/api-extractor-model/src/model/ApiProperty.ts @@ -9,7 +9,6 @@ import { } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference'; import { ApiItemKind } from '../items/ApiItem'; import { ApiProtectedMixin, IApiProtectedMixinOptions } from '../mixins/ApiProtectedMixin'; -import { ApiReadonlyMixin, IApiReadonlyMixinOptions } from '../mixins/ApiReadonlyMixin'; import { ApiStaticMixin, IApiStaticMixinOptions } from '../mixins/ApiStaticMixin'; import { ApiPropertyItem, IApiPropertyItemOptions } from '../items/ApiPropertyItem'; @@ -20,7 +19,6 @@ import { ApiPropertyItem, IApiPropertyItemOptions } from '../items/ApiPropertyIt export interface IApiPropertyOptions extends IApiPropertyItemOptions, IApiProtectedMixinOptions, - IApiReadonlyMixinOptions, IApiStaticMixinOptions {} /** @@ -57,7 +55,7 @@ export interface IApiPropertyOptions * * @public */ -export class ApiProperty extends ApiProtectedMixin(ApiReadonlyMixin(ApiStaticMixin(ApiPropertyItem))) { +export class ApiProperty extends ApiProtectedMixin(ApiStaticMixin(ApiPropertyItem)) { public constructor(options: IApiPropertyOptions) { super(options); } diff --git a/libraries/api-extractor-model/src/model/ApiPropertySignature.ts b/libraries/api-extractor-model/src/model/ApiPropertySignature.ts index fd9fe8836cc..6a5c561f840 100644 --- a/libraries/api-extractor-model/src/model/ApiPropertySignature.ts +++ b/libraries/api-extractor-model/src/model/ApiPropertySignature.ts @@ -9,12 +9,12 @@ import { } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference'; import { ApiItemKind } from '../items/ApiItem'; import { ApiPropertyItem, IApiPropertyItemOptions } from '../items/ApiPropertyItem'; -import { ApiReadonlyMixin, IApiReadonlyMixinOptions } from '../mixins/ApiReadonlyMixin'; + /** * Constructor options for {@link ApiPropertySignature}. * @public */ -export interface IApiPropertySignatureOptions extends IApiPropertyItemOptions, IApiReadonlyMixinOptions {} +export interface IApiPropertySignatureOptions extends IApiPropertyItemOptions {} /** * Represents a TypeScript property declaration that belongs to an `ApiInterface`. @@ -38,7 +38,7 @@ export interface IApiPropertySignatureOptions extends IApiPropertyItemOptions, I * * @public */ -export class ApiPropertySignature extends ApiReadonlyMixin(ApiPropertyItem) { +export class ApiPropertySignature extends ApiPropertyItem { public constructor(options: IApiPropertySignatureOptions) { super(options); } From 2d7dcbe53aa7554f3bd55cfefde523d8338254bc Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Tue, 7 Jun 2022 01:42:54 -0700 Subject: [PATCH 11/14] Cosmetic change: alphabetize the inheritance order for mixin classes --- .../api-extractor-model/src/model/ApiConstructor.ts | 2 +- libraries/api-extractor-model/src/model/ApiMethod.ts | 10 +++++----- libraries/api-extractor-model/src/model/ApiVariable.ts | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/libraries/api-extractor-model/src/model/ApiConstructor.ts b/libraries/api-extractor-model/src/model/ApiConstructor.ts index 51261d157da..c25a7e1e4a5 100644 --- a/libraries/api-extractor-model/src/model/ApiConstructor.ts +++ b/libraries/api-extractor-model/src/model/ApiConstructor.ts @@ -50,7 +50,7 @@ export interface IApiConstructorOptions * @public */ export class ApiConstructor extends ApiParameterListMixin( - ApiReleaseTagMixin(ApiProtectedMixin(ApiDeclaredItem)) + ApiProtectedMixin(ApiReleaseTagMixin(ApiDeclaredItem)) ) { public constructor(options: IApiConstructorOptions) { super(options); diff --git a/libraries/api-extractor-model/src/model/ApiMethod.ts b/libraries/api-extractor-model/src/model/ApiMethod.ts index d461ef67b1e..c5b71ae03a5 100644 --- a/libraries/api-extractor-model/src/model/ApiMethod.ts +++ b/libraries/api-extractor-model/src/model/ApiMethod.ts @@ -27,13 +27,13 @@ import { ApiOptionalMixin, IApiOptionalMixinOptions } from '../mixins/ApiOptiona */ export interface IApiMethodOptions extends IApiNameMixinOptions, - IApiTypeParameterListMixinOptions, + IApiOptionalMixinOptions, IApiParameterListMixinOptions, IApiProtectedMixinOptions, IApiReleaseTagMixinOptions, IApiReturnTypeMixinOptions, IApiStaticMixinOptions, - IApiOptionalMixinOptions, + IApiTypeParameterListMixinOptions, IApiDeclaredItemOptions {} /** @@ -58,10 +58,10 @@ export interface IApiMethodOptions * @public */ export class ApiMethod extends ApiNameMixin( - ApiTypeParameterListMixin( + ApiOptionalMixin( ApiParameterListMixin( - ApiReleaseTagMixin( - ApiReturnTypeMixin(ApiProtectedMixin(ApiStaticMixin(ApiOptionalMixin(ApiDeclaredItem)))) + ApiProtectedMixin( + ApiReleaseTagMixin(ApiReturnTypeMixin(ApiStaticMixin(ApiTypeParameterListMixin(ApiDeclaredItem)))) ) ) ) diff --git a/libraries/api-extractor-model/src/model/ApiVariable.ts b/libraries/api-extractor-model/src/model/ApiVariable.ts index 00eaed12838..c476693dabb 100644 --- a/libraries/api-extractor-model/src/model/ApiVariable.ts +++ b/libraries/api-extractor-model/src/model/ApiVariable.ts @@ -22,8 +22,8 @@ import { DeserializerContext } from './DeserializerContext'; export interface IApiVariableOptions extends IApiNameMixinOptions, IApiReleaseTagMixinOptions, - IApiDeclaredItemOptions, - IApiReadonlyMixinOptions { + IApiReadonlyMixinOptions, + IApiDeclaredItemOptions { variableTypeTokenRange: IExcerptTokenRange; } @@ -51,7 +51,7 @@ export interface IApiVariableJson extends IApiDeclaredItemJson { * * @public */ -export class ApiVariable extends ApiReadonlyMixin(ApiNameMixin(ApiReleaseTagMixin(ApiDeclaredItem))) { +export class ApiVariable extends ApiNameMixin(ApiReleaseTagMixin(ApiReadonlyMixin(ApiDeclaredItem))) { /** * An {@link Excerpt} that describes the type of the variable. */ From d2b48daaf781fcc17f25e58ef1199386fc4e0fab Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Tue, 7 Jun 2022 01:44:15 -0700 Subject: [PATCH 12/14] rush build --- .../etc/api-documenter-test.api.json | 75 ++++++++++--------- .../api-extractor-scenarios.api.json | 28 +++---- .../api-extractor-scenarios.api.json | 2 +- .../api-extractor-scenarios.api.json | 2 +- .../api-extractor-scenarios.api.json | 4 +- .../api-extractor-scenarios.api.json | 24 +++--- .../api-extractor-scenarios.api.json | 4 +- .../api-extractor-scenarios.api.json | 6 +- .../api-extractor-scenarios.api.json | 4 +- .../api-extractor-scenarios.api.json | 8 +- .../api-extractor-scenarios.api.json | 28 +++---- .../api-extractor-scenarios.api.json | 16 ++-- .../api-extractor-scenarios.api.json | 14 ++-- .../api-extractor-scenarios.api.json | 20 ++--- .../workspace/common/pnpm-lock.yaml | 30 ++++---- common/reviews/api/api-extractor-model.api.md | 28 ++++++- 16 files changed, 161 insertions(+), 132 deletions(-) diff --git a/build-tests/api-documenter-test/etc/api-documenter-test.api.json b/build-tests/api-documenter-test/etc/api-documenter-test.api.json index 049c4994d3d..9431f20e9fd 100644 --- a/build-tests/api-documenter-test/etc/api-documenter-test.api.json +++ b/build-tests/api-documenter-test/etc/api-documenter-test.api.json @@ -209,9 +209,9 @@ "text": "number" } ], + "isReadonly": true, "releaseTag": "Public", "name": "constVariable", - "isReadonly": true, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 @@ -301,8 +301,8 @@ "text": "constructor();" } ], - "isProtected": false, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [] }, @@ -324,8 +324,8 @@ "text": ");" } ], - "isProtected": false, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 2, "parameters": [ { @@ -403,16 +403,16 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 1, "endIndex": 2 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [], + "isOptional": false, "name": "deprecatedExample" }, { @@ -449,14 +449,13 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 5, "endIndex": 6 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [ { @@ -476,6 +475,7 @@ "isOptional": false } ], + "isOptional": false, "name": "exampleFunction" }, { @@ -504,14 +504,13 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 3, "endIndex": 4 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 2, "parameters": [ { @@ -523,6 +522,7 @@ "isOptional": false } ], + "isOptional": false, "name": "exampleFunction" }, { @@ -573,14 +573,26 @@ "text": ";" } ], - "isOptional": false, + "typeParameters": [ + { + "typeParameterName": "T", + "constraintTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "defaultTypeTokenRange": { + "startIndex": 4, + "endIndex": 5 + } + } + ], "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 8, "endIndex": 9 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [ { @@ -592,19 +604,7 @@ "isOptional": false } ], - "typeParameters": [ - { - "typeParameterName": "T", - "constraintTokenRange": { - "startIndex": 1, - "endIndex": 2 - }, - "defaultTypeTokenRange": { - "startIndex": 4, - "endIndex": 5 - } - } - ], + "isOptional": false, "name": "genericWithConstraintAndDefault" }, { @@ -625,16 +625,16 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 1, "endIndex": 2 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [], + "isOptional": false, "name": "interestingEdgeCases" }, { @@ -723,14 +723,13 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 3, "endIndex": 4 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [ { @@ -742,6 +741,7 @@ "isOptional": true } ], + "isOptional": false, "name": "optionalParamFunction" }, { @@ -829,7 +829,8 @@ "startIndex": 1, "endIndex": 2 }, - "isStatic": true + "isStatic": true, + "isProtected": false }, { "kind": "Method", @@ -865,14 +866,13 @@ "text": ";" } ], - "isOptional": false, "isStatic": true, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 5, "endIndex": 6 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [ { @@ -892,6 +892,7 @@ "isOptional": false } ], + "isOptional": false, "name": "sumWithExample" }, { @@ -912,16 +913,16 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 1, "endIndex": 2 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [], + "isOptional": false, "name": "tableExample" }, { @@ -1236,9 +1237,9 @@ "text": "unique symbol" } ], + "isReadonly": true, "releaseTag": "Public", "name": "example", - "isReadonly": true, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 @@ -2471,9 +2472,9 @@ "text": "boolean" } ], + "isReadonly": false, "releaseTag": "Public", "name": "nestedVariable", - "isReadonly": false, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 @@ -2520,14 +2521,13 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 3, "endIndex": 4 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [ { @@ -2539,6 +2539,7 @@ "isOptional": false } ], + "isOptional": false, "name": "addHandler" } ], diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json index 0c9c6683073..ddc84f4d697 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json @@ -201,16 +201,16 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 1, "endIndex": 2 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [], + "isOptional": false, "name": "member" } ], @@ -255,14 +255,13 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 3, "endIndex": 4 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [ { @@ -274,6 +273,7 @@ "isOptional": false } ], + "isOptional": false, "name": "method1" }, { @@ -303,16 +303,16 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 1, "endIndex": 4 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [], + "isOptional": false, "name": "method2" } ], @@ -466,9 +466,9 @@ "text": "object[]" } ], + "isReadonly": false, "releaseTag": "Public", "name": "constVariable", - "isReadonly": false, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 @@ -488,9 +488,9 @@ "text": "object[]" } ], + "isReadonly": false, "releaseTag": "Public", "name": "variable", - "isReadonly": false, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 @@ -607,16 +607,16 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 1, "endIndex": 2 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [], + "isOptional": false, "name": "member" }, { @@ -645,14 +645,13 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 3, "endIndex": 4 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [ { @@ -664,6 +663,7 @@ "isOptional": true } ], + "isOptional": false, "name": "optionalParamMethod" }, { @@ -705,6 +705,7 @@ "text": "readonly someReadonlyProp = 5;" } ], + "isReadonly": true, "isOptional": false, "releaseTag": "Public", "name": "someReadonlyProp", @@ -733,6 +734,7 @@ "text": ";" } ], + "isReadonly": true, "isOptional": false, "releaseTag": "Public", "name": "someReadonlyPropWithType", @@ -793,9 +795,9 @@ "text": "string" } ], + "isReadonly": true, "releaseTag": "Public", "name": "VARIABLE", - "isReadonly": true, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/defaultExportOfEntryPoint2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/defaultExportOfEntryPoint2/api-extractor-scenarios.api.json index 6b9c010f6ec..cf3343522f6 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/defaultExportOfEntryPoint2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/defaultExportOfEntryPoint2/api-extractor-scenarios.api.json @@ -184,9 +184,9 @@ "text": "() => void" } ], + "isReadonly": true, "releaseTag": "Public", "name": "defaultFunctionStatement", - "isReadonly": true, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/defaultExportOfEntryPoint4/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/defaultExportOfEntryPoint4/api-extractor-scenarios.api.json index 6fef85435c6..6ad2778b65e 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/defaultExportOfEntryPoint4/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/defaultExportOfEntryPoint4/api-extractor-scenarios.api.json @@ -184,9 +184,9 @@ "text": "\"literal\"" } ], + "isReadonly": true, "releaseTag": "Public", "name": "_default", - "isReadonly": true, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.json index 760eaee1338..82a4e4577d3 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.json @@ -276,14 +276,13 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 3, "endIndex": 4 }, "releaseTag": "Beta", + "isProtected": false, "overloadIndex": 1, "parameters": [ { @@ -295,6 +294,7 @@ "isOptional": false } ], + "isOptional": false, "name": "myMethod" } ], diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/api-extractor-scenarios.api.json index 185efd3af43..d9924f69917 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences2/api-extractor-scenarios.api.json @@ -201,16 +201,16 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 1, "endIndex": 2 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [], + "isOptional": false, "name": "methodA1" }, { @@ -231,16 +231,16 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 1, "endIndex": 2 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [], + "isOptional": false, "name": "methodA3" } ], @@ -277,16 +277,16 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 1, "endIndex": 2 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [], + "isOptional": false, "name": "methodB2" }, { @@ -307,16 +307,16 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 1, "endIndex": 2 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [], + "isOptional": false, "name": "methodB4" } ], @@ -353,16 +353,16 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 1, "endIndex": 2 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [], + "isOptional": false, "name": "method1" }, { @@ -383,16 +383,16 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 1, "endIndex": 2 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [], + "isOptional": false, "name": "method2" } ], diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json index e378390dcb7..158b62ad07d 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json @@ -257,16 +257,16 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 1, "endIndex": 2 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [], + "isOptional": false, "name": "myMethod" } ], diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/excerptTokens/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/excerptTokens/api-extractor-scenarios.api.json index 37b4f4c0f2e..c145dad23bb 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/excerptTokens/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/excerptTokens/api-extractor-scenarios.api.json @@ -184,9 +184,9 @@ "text": "number" } ], + "isReadonly": false, "releaseTag": "Public", "name": "MY_CONSTANT", - "isReadonly": false, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 @@ -239,14 +239,13 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 5, "endIndex": 6 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [ { @@ -266,6 +265,7 @@ "isOptional": false } ], + "isOptional": false, "name": "someMethod" } ], diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/exportImportStarAs/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/exportImportStarAs/api-extractor-scenarios.api.json index 8f9c080a6e6..96cc42782c0 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/exportImportStarAs/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/exportImportStarAs/api-extractor-scenarios.api.json @@ -252,9 +252,9 @@ "text": "string" } ], + "isReadonly": true, "releaseTag": "Public", "name": "calucatorVersion", - "isReadonly": true, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 @@ -404,9 +404,9 @@ "text": "string" } ], + "isReadonly": true, "releaseTag": "Public", "name": "calucatorVersion", - "isReadonly": true, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/functionOverload/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/functionOverload/api-extractor-scenarios.api.json index 724f1432540..78b861a36dd 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/functionOverload/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/functionOverload/api-extractor-scenarios.api.json @@ -397,14 +397,13 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 5, "endIndex": 6 }, "releaseTag": "Beta", + "isProtected": false, "overloadIndex": 2, "parameters": [ { @@ -424,6 +423,7 @@ "isOptional": false } ], + "isOptional": false, "name": "combine" }, { @@ -460,14 +460,13 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 5, "endIndex": 6 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 3, "parameters": [ { @@ -487,6 +486,7 @@ "isOptional": false } ], + "isOptional": false, "name": "combine" } ], diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/internationalCharacters/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/internationalCharacters/api-extractor-scenarios.api.json index f51e8847ea1..e04bf18af4a 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/internationalCharacters/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/internationalCharacters/api-extractor-scenarios.api.json @@ -210,16 +210,6 @@ "text": ";" } ], - "isOptional": false, - "isStatic": false, - "isProtected": false, - "returnTypeTokenRange": { - "startIndex": 3, - "endIndex": 4 - }, - "releaseTag": "Public", - "overloadIndex": 1, - "parameters": [], "typeParameters": [ { "typeParameterName": "T", @@ -233,6 +223,16 @@ } } ], + "isStatic": false, + "returnTypeTokenRange": { + "startIndex": 3, + "endIndex": 4 + }, + "releaseTag": "Public", + "isProtected": false, + "overloadIndex": 1, + "parameters": [], + "isOptional": false, "name": "\"invalid chars\"" }, { @@ -262,14 +262,13 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 3, "endIndex": 4 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [ { @@ -281,6 +280,7 @@ "isOptional": false } ], + "isOptional": false, "name": "memberĪ”" }, { @@ -301,16 +301,16 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 1, "endIndex": 2 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [], + "isOptional": false, "name": "validChars" } ], diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json index c8733be5632..c2084c4a386 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json @@ -2,7 +2,7 @@ "metadata": { "toolPackage": "@microsoft/api-extractor", "toolVersion": "[test mode]", - "schemaVersion": 1005, + "schemaVersion": 1006, "oldestForwardsCompatibleVersion": 1001, "tsdocConfig": { "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", @@ -223,9 +223,9 @@ "text": "FOO = \"foo\"" } ], + "isReadonly": true, "releaseTag": "Public", "name": "FOO", - "isReadonly": true, "variableTypeTokenRange": { "startIndex": 0, "endIndex": 0 @@ -271,7 +271,8 @@ "startIndex": 1, "endIndex": 2 }, - "isStatic": false + "isStatic": false, + "isProtected": false }, { "kind": "Property", @@ -313,7 +314,8 @@ "startIndex": 1, "endIndex": 2 }, - "isStatic": false + "isStatic": false, + "isProtected": false }, { "kind": "Property", @@ -342,7 +344,8 @@ "startIndex": 1, "endIndex": 2 }, - "isStatic": true + "isStatic": true, + "isProtected": false }, { "kind": "Property", @@ -371,7 +374,8 @@ "startIndex": 1, "endIndex": 2 }, - "isStatic": false + "isStatic": false, + "isProtected": false } ], "implementsTokenRanges": [] diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/api-extractor-scenarios.api.json index e9dd4d1b34d..d5cafe486ab 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/api-extractor-scenarios.api.json @@ -235,16 +235,16 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 1, "endIndex": 3 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [], + "isOptional": false, "name": "member2" } ], @@ -289,14 +289,13 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 3, "endIndex": 4 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [ { @@ -308,6 +307,7 @@ "isOptional": false } ], + "isOptional": false, "name": "tryLoadFromFile" } ], @@ -344,16 +344,16 @@ "text": ";" } ], - "isOptional": false, "isStatic": false, - "isProtected": false, "returnTypeTokenRange": { "startIndex": 1, "endIndex": 2 }, "releaseTag": "Public", + "isProtected": false, "overloadIndex": 1, "parameters": [], + "isOptional": false, "name": "member1" } ], @@ -373,9 +373,9 @@ "text": "(o: {\n a: number;\n b(): string;\n}) => void" } ], + "isReadonly": true, "releaseTag": "Public", "name": "exampleD", - "isReadonly": true, "variableTypeTokenRange": { "startIndex": 1, "endIndex": 2 diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/typeParameters/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/typeParameters/api-extractor-scenarios.api.json index 50102ff1a5f..74e92fe01a7 100644 --- a/build-tests/api-extractor-scenarios/etc/test-outputs/typeParameters/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/test-outputs/typeParameters/api-extractor-scenarios.api.json @@ -201,16 +201,6 @@ "text": ";" } ], - "isOptional": false, - "isStatic": false, - "isProtected": false, - "returnTypeTokenRange": { - "startIndex": 1, - "endIndex": 2 - }, - "releaseTag": "Public", - "overloadIndex": 1, - "parameters": [], "typeParameters": [ { "typeParameterName": "T", @@ -224,6 +214,16 @@ } } ], + "isStatic": false, + "returnTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "releaseTag": "Public", + "isProtected": false, + "overloadIndex": 1, + "parameters": [], + "isOptional": false, "name": "method" } ], diff --git a/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml b/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml index 5291a3421c7..9fab90318d7 100644 --- a/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml +++ b/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml @@ -5,13 +5,13 @@ importers: typescript-newest-test: specifiers: '@rushstack/eslint-config': file:rushstack-eslint-config-2.6.0.tgz - '@rushstack/heft': file:rushstack-heft-0.45.4.tgz + '@rushstack/heft': file:rushstack-heft-0.45.5.tgz eslint: ~8.7.0 tslint: ~5.20.1 typescript: ~4.6.3 devDependencies: '@rushstack/eslint-config': file:../temp/tarballs/rushstack-eslint-config-2.6.0.tgz_eslint@8.7.0+typescript@4.6.3 - '@rushstack/heft': file:../temp/tarballs/rushstack-heft-0.45.4.tgz + '@rushstack/heft': file:../temp/tarballs/rushstack-heft-0.45.5.tgz eslint: 8.7.0 tslint: 5.20.1_typescript@4.6.3 typescript: 4.6.3 @@ -19,13 +19,13 @@ importers: typescript-v3-test: specifiers: '@rushstack/eslint-config': file:rushstack-eslint-config-2.6.0.tgz - '@rushstack/heft': file:rushstack-heft-0.45.4.tgz + '@rushstack/heft': file:rushstack-heft-0.45.5.tgz eslint: ~8.7.0 tslint: ~5.20.1 typescript: ~4.6.3 devDependencies: '@rushstack/eslint-config': file:../temp/tarballs/rushstack-eslint-config-2.6.0.tgz_eslint@8.7.0+typescript@4.6.3 - '@rushstack/heft': file:../temp/tarballs/rushstack-heft-0.45.4.tgz + '@rushstack/heft': file:../temp/tarballs/rushstack-heft-0.45.5.tgz eslint: 8.7.0 tslint: 5.20.1_typescript@4.6.3 typescript: 4.6.3 @@ -831,7 +831,7 @@ packages: dev: true /glob-escape/0.0.2: - resolution: {integrity: sha1-nCf3gh7RwTd1gvPv2VWOP2dWKO0=} + resolution: {integrity: sha512-L/cXYz8x7qer1HAyUQ+mbjcUsJVdpRxpAf7CwqHoNBs9vTpABlGfNN4tzkDxt+u3Z7ZncVyKlCNPtzb0R/7WbA==} engines: {node: '>= 0.10'} dev: true @@ -850,7 +850,7 @@ packages: dev: true /glob/7.0.6: - resolution: {integrity: sha1-IRuvr0nlJbjNkyYNFKsTYVKz9Xo=} + resolution: {integrity: sha512-f8c0rE8JiCxpa52kWPAOa3ZaYEnzofDzCQLCn3Vdk0Z5OVLq3BsRFJI4S4ykpeVW6QMGBUkMeUpoEgWnMTnw5Q==} dependencies: fs.realpath: 1.0.0 inflight: 1.0.6 @@ -1073,7 +1073,7 @@ packages: dev: true /jju/1.4.0: - resolution: {integrity: sha1-o6vicYryQaKykE+EpiWXDzia4yo=} + resolution: {integrity: sha512-8wb9Yw966OSxApiCt0K3yNJL8pnNeIv+OEq2YMidz4FKP6nonSRoOXc80iXY4JaN2FC11B9qsNmDsm+ZOfMROA==} dev: true /js-tokens/4.0.0: @@ -1104,7 +1104,7 @@ packages: dev: true /jsonfile/4.0.0: - resolution: {integrity: sha1-h3Gq4HmbZAdrdmQPygWPnBDjPss=} + resolution: {integrity: sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==} optionalDependencies: graceful-fs: 4.2.6 dev: true @@ -1131,11 +1131,11 @@ packages: dev: true /lodash.get/4.4.2: - resolution: {integrity: sha1-LRd/ZS+jHpObRDjVNBSZ36OCXpk=} + resolution: {integrity: sha512-z+Uw/vLuy6gQe8cfaFWD7p0wVv8fJl3mbzXh33RS+0oW2wvUqiRXiQ69gLWSLpgB5/6sU+r6BlQR0MBILadqTQ==} dev: true /lodash.isequal/4.5.0: - resolution: {integrity: sha1-QVxEePK8wwEgwizhDtMib30+GOA=} + resolution: {integrity: sha512-pDo3lu8Jhfjqls6GkMgpahsF9kCyayhgykjyLMNFTKWrpVdAQtYyB4muAMWozBB4ig/dtWAmsMxLEI8wuz+DYQ==} dev: true /lodash.merge/4.6.2: @@ -1200,7 +1200,7 @@ packages: dev: true /object-assign/4.1.1: - resolution: {integrity: sha1-IQmtx5ZYh8/AXLvUQsrIv7s2CGM=} + resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==} engines: {node: '>=0.10.0'} dev: true @@ -1258,7 +1258,7 @@ packages: dev: true /once/1.4.0: - resolution: {integrity: sha1-WDsap3WWHUsROsF9nFC6753Xa9E=} + resolution: {integrity: sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==} dependencies: wrappy: 1.0.2 dev: true @@ -1753,10 +1753,10 @@ packages: - typescript dev: true - file:../temp/tarballs/rushstack-heft-0.45.4.tgz: - resolution: {tarball: file:../temp/tarballs/rushstack-heft-0.45.4.tgz} + file:../temp/tarballs/rushstack-heft-0.45.5.tgz: + resolution: {tarball: file:../temp/tarballs/rushstack-heft-0.45.5.tgz} name: '@rushstack/heft' - version: 0.45.4 + version: 0.45.5 engines: {node: '>=10.13.0'} hasBin: true dependencies: diff --git a/common/reviews/api/api-extractor-model.api.md b/common/reviews/api/api-extractor-model.api.md index 51e591204da..f42a9327df5 100644 --- a/common/reviews/api/api-extractor-model.api.md +++ b/common/reviews/api/api-extractor-model.api.md @@ -522,6 +522,22 @@ export namespace ApiProtectedMixin { export function isBaseClassOf(apiItem: ApiItem): apiItem is ApiProtectedMixin; } +// @public +export function ApiReadonlyMixin(baseClass: TBaseClass): TBaseClass & (new (...args: any[]) => ApiReadonlyMixin); + +// @public +export interface ApiReadonlyMixin extends ApiItem { + // (undocumented) + readonly isReadonly: boolean; + // (undocumented) + serializeInto(jsonObject: Partial): void; +} + +// @public +export namespace ApiReadonlyMixin { + export function isBaseClassOf(apiItem: ApiItem): apiItem is ApiReadonlyMixin; +} + // @public export function ApiReleaseTagMixin(baseClass: TBaseClass): TBaseClass & (new (...args: any[]) => ApiReleaseTagMixin); @@ -736,7 +752,7 @@ export interface IApiItemOptions { } // @public -export interface IApiMethodOptions extends IApiNameMixinOptions, IApiTypeParameterListMixinOptions, IApiParameterListMixinOptions, IApiProtectedMixinOptions, IApiReleaseTagMixinOptions, IApiReturnTypeMixinOptions, IApiStaticMixinOptions, IApiOptionalMixinOptions, IApiDeclaredItemOptions { +export interface IApiMethodOptions extends IApiNameMixinOptions, IApiOptionalMixinOptions, IApiParameterListMixinOptions, IApiProtectedMixinOptions, IApiReleaseTagMixinOptions, IApiReturnTypeMixinOptions, IApiStaticMixinOptions, IApiTypeParameterListMixinOptions, IApiDeclaredItemOptions { } // @public (undocumented) @@ -791,7 +807,7 @@ export interface IApiParameterOptions { } // @public -export interface IApiPropertyItemOptions extends IApiNameMixinOptions, IApiReleaseTagMixinOptions, IApiOptionalMixinOptions, IApiDeclaredItemOptions { +export interface IApiPropertyItemOptions extends IApiNameMixinOptions, IApiReleaseTagMixinOptions, IApiOptionalMixinOptions, IApiReadonlyMixinOptions, IApiDeclaredItemOptions { // (undocumented) propertyTypeTokenRange: IExcerptTokenRange; } @@ -810,6 +826,12 @@ export interface IApiProtectedMixinOptions extends IApiItemOptions { isProtected: boolean; } +// @public +export interface IApiReadonlyMixinOptions extends IApiItemOptions { + // (undocumented) + isReadonly: boolean; +} + // @public export interface IApiReleaseTagMixinOptions extends IApiItemOptions { // (undocumented) @@ -851,7 +873,7 @@ export interface IApiTypeParameterOptions { } // @public -export interface IApiVariableOptions extends IApiNameMixinOptions, IApiReleaseTagMixinOptions, IApiDeclaredItemOptions { +export interface IApiVariableOptions extends IApiNameMixinOptions, IApiReleaseTagMixinOptions, IApiReadonlyMixinOptions, IApiDeclaredItemOptions { // (undocumented) variableTypeTokenRange: IExcerptTokenRange; } From e469248b8ea7b7c997df964a89fdf7d7cebca037 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Tue, 7 Jun 2022 02:05:22 -0700 Subject: [PATCH 13/14] Add API documentation for ApiReadonlyMixin.isReadonly --- common/reviews/api/api-extractor-model.api.md | 1 - .../src/mixins/ApiReadonlyMixin.ts | 24 +++++++++++++++++++ 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/common/reviews/api/api-extractor-model.api.md b/common/reviews/api/api-extractor-model.api.md index f42a9327df5..3e248e4d580 100644 --- a/common/reviews/api/api-extractor-model.api.md +++ b/common/reviews/api/api-extractor-model.api.md @@ -527,7 +527,6 @@ export function ApiReadonlyMixin(baseCla // @public export interface ApiReadonlyMixin extends ApiItem { - // (undocumented) readonly isReadonly: boolean; // (undocumented) serializeInto(jsonObject: Partial): void; diff --git a/libraries/api-extractor-model/src/mixins/ApiReadonlyMixin.ts b/libraries/api-extractor-model/src/mixins/ApiReadonlyMixin.ts index 0c6c6069cdb..45de9a603bd 100644 --- a/libraries/api-extractor-model/src/mixins/ApiReadonlyMixin.ts +++ b/libraries/api-extractor-model/src/mixins/ApiReadonlyMixin.ts @@ -36,6 +36,30 @@ const _isReadonly: unique symbol = Symbol('ApiReadonlyMixin._isReadonly'); */ // eslint-disable-next-line @typescript-eslint/naming-convention export interface ApiReadonlyMixin extends ApiItem { + /** + * Indicates that the API item's value cannot be assigned by an external consumer. + * + * @remarks + * Examples of API items that would be considered "read only" by API Extractor: + * + * - A class or interface's property that has the `readonly` modifier. + * + * - A variable that has the `const` modifier. + * + * - A property or variable whose TSDoc comment includes the `@readonly` tag. + * + * - A property declaration with a getter but no setter. + * + * Note that if the `readonly` keyword appears in a type annotation, this does not + * guarantee that that the API item will be considered readonly. For example: + * + * ```ts + * declare class C { + * // isReadonly=false in this case, because C.x is assignable + * public x: readonly string[]; + * } + * ``` + */ readonly isReadonly: boolean; serializeInto(jsonObject: Partial): void; From e0dfbb2cf9c568eb75ddb7d5a58511e001d4ba22 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Tue, 7 Jun 2022 02:06:12 -0700 Subject: [PATCH 14/14] Update change files --- .../api-readonly-mixin_2022-05-19-20-18.json | 2 +- .../api-extractor-model/protected-mixin_2022-05-20-22-50.json | 2 +- .../api-extractor/api-readonly-mixin_2022-05-19-20-18.json | 2 +- .../api-extractor/protected-mixin_2022-05-20-22-50.json | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/common/changes/@microsoft/api-extractor-model/api-readonly-mixin_2022-05-19-20-18.json b/common/changes/@microsoft/api-extractor-model/api-readonly-mixin_2022-05-19-20-18.json index acca3ad737a..b0380433357 100644 --- a/common/changes/@microsoft/api-extractor-model/api-readonly-mixin_2022-05-19-20-18.json +++ b/common/changes/@microsoft/api-extractor-model/api-readonly-mixin_2022-05-19-20-18.json @@ -2,7 +2,7 @@ "changes": [ { "packageName": "@microsoft/api-extractor-model", - "comment": "Adding isReadonly field to the models of relevant api pieces.", + "comment": "Add an \"isReadonly\" field to ApiProperty, ApiPropertySignature, and ApiVariable", "type": "minor" } ], diff --git a/common/changes/@microsoft/api-extractor-model/protected-mixin_2022-05-20-22-50.json b/common/changes/@microsoft/api-extractor-model/protected-mixin_2022-05-20-22-50.json index dec7b0ee3ed..8d4390c4dbd 100644 --- a/common/changes/@microsoft/api-extractor-model/protected-mixin_2022-05-20-22-50.json +++ b/common/changes/@microsoft/api-extractor-model/protected-mixin_2022-05-20-22-50.json @@ -2,7 +2,7 @@ "changes": [ { "packageName": "@microsoft/api-extractor-model", - "comment": "Add parsing logic to parse whether a class constructor, property, or method has the 'protected' modifier.", + "comment": "Add an \"isProtected\" field to ApiConstructor, ApiMethod, and ApiProperty", "type": "minor" } ], diff --git a/common/changes/@microsoft/api-extractor/api-readonly-mixin_2022-05-19-20-18.json b/common/changes/@microsoft/api-extractor/api-readonly-mixin_2022-05-19-20-18.json index 681547e7226..000ad71a5d1 100644 --- a/common/changes/@microsoft/api-extractor/api-readonly-mixin_2022-05-19-20-18.json +++ b/common/changes/@microsoft/api-extractor/api-readonly-mixin_2022-05-19-20-18.json @@ -2,7 +2,7 @@ "changes": [ { "packageName": "@microsoft/api-extractor", - "comment": "Adding readonlyMixin for Api Extractor", + "comment": "Add an \"isReadonly\" field to the doc model to indicate whether a property or variable is readonly", "type": "minor" } ], diff --git a/common/changes/@microsoft/api-extractor/protected-mixin_2022-05-20-22-50.json b/common/changes/@microsoft/api-extractor/protected-mixin_2022-05-20-22-50.json index bf444adf5ac..1099b359645 100644 --- a/common/changes/@microsoft/api-extractor/protected-mixin_2022-05-20-22-50.json +++ b/common/changes/@microsoft/api-extractor/protected-mixin_2022-05-20-22-50.json @@ -2,7 +2,7 @@ "changes": [ { "packageName": "@microsoft/api-extractor", - "comment": "Add an ApiParameterMixin that adds an isProtected parameter to class constructor, property, and method API items.", + "comment": "Add an \"isProtected\" field to the doc model to indicate protected class members", "type": "minor" } ],