[api-extractor] addressing comments

marshallstock · marshallstock · commit 02612834883e · 2022-05-19T17:52:53.000-07:00
diff --git a/apps/api-extractor/src/generators/ApiModelGenerator.ts b/apps/api-extractor/src/generators/ApiModelGenerator.ts
@@ -653,16 +653,14 @@ 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,
         docComment,
         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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -379,7 +379,6 @@
               "text": "export interface GenericInterface<T> "
             }
           ],
-          "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
@@ -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
@@ -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
@@ -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
@@ -494,8 +494,10 @@ export class ApiPropertyItem extends ApiPropertyItem_base {
     serializeInto(jsonObject: Partial<IApiPropertyItemJson>): 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
@@ -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
@@ -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
@@ -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);
   }

Original file line number	Diff line number	Diff line change
`@@ -406,7 +406,6 @@`
`406`	`406`	`"text": "export interface IInterface "`
`407`	`407`	`}`
`408`	`408`	`],`
`409`		`- "isReadonly": false,`
`410`	`409`	`"releaseTag": "Public",`
`411`	`410`	`"name": "IInterface",`
`412`	`411`	`"members": [`
Original file line number	Diff line number	Diff line change
`@@ -180,7 +180,6 @@`
`180`	`180`	`"text": "export interface A "`
`181`	`181`	`}`
`182`	`182`	`],`
`183`		`- "isReadonly": false,`
`184`	`183`	`"releaseTag": "Public",`
`185`	`184`	`"name": "A",`
`186`	`185`	`"members": [`