Merge pull request #3396 from zelliott/handle-setters

[api-extractor] Generate documentation for setters without getters
microsoft · May 14, 2022 · 5f56cf6 · 5f56cf6
2 parents e9a2b58 + ca2e07a
commit 5f56cf6
Show file tree

Hide file tree

Showing 9 changed files with 92 additions and 5 deletions.
diff --git a/apps/api-extractor/src/generators/ApiModelGenerator.ts b/apps/api-extractor/src/generators/ApiModelGenerator.ts
@@ -202,6 +202,10 @@ export class ApiModelGenerator {
         this._processApiProperty(astDeclaration, exportedName, parentApiItem);
         break;
 
+      case ts.SyntaxKind.SetAccessor:
+        this._processApiProperty(astDeclaration, exportedName, parentApiItem);
+        break;
+
       case ts.SyntaxKind.IndexSignature:
         this._processApiIndexSignature(astDeclaration, exportedName, parentApiItem);
         break;
@@ -817,13 +821,17 @@ export class ApiModelGenerator {
     let apiProperty: ApiProperty | undefined = parentApiItem.tryGetMemberByKey(containerKey) as ApiProperty;
 
     if (apiProperty === undefined) {
-      const propertyDeclaration: ts.PropertyDeclaration =
-        astDeclaration.declaration as ts.PropertyDeclaration;
-
       const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];
 
       const propertyTypeTokenRange: IExcerptTokenRange = ExcerptBuilder.createEmptyTokenRange();
-      nodesToCapture.push({ node: propertyDeclaration.type, tokenRange: propertyTypeTokenRange });
+
+      // If the property declaration's type is `undefined`, then we're processing a setter with no corresponding
+      // getter. Use the parameter type instead (note that TypeScript always reports an error if a setter
+      // does not have exactly one parameter).
+      const propertyTypeNode: ts.TypeNode | undefined =
+        (astDeclaration.declaration as ts.PropertyDeclaration | ts.GetAccessorDeclaration).type ||
+        (astDeclaration.declaration as ts.SetAccessorDeclaration).parameters[0].type;
+      nodesToCapture.push({ node: propertyTypeNode, tokenRange: propertyTypeTokenRange });
 
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
       const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);

diff --git a/build-tests/api-documenter-test/config/api-extractor.json b/build-tests/api-documenter-test/config/api-extractor.json
@@ -18,5 +18,14 @@
     "enabled": false
   },
 
-  "testMode": true
+  "testMode": true,
+
+  "messages": {
+    "extractorMessageReporting": {
+      // Purposefully disabled for the `writeonlyProperty` test case.
+      "ae-missing-getter": {
+        "logLevel": "none"
+      }
+    }
+  }
 }
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
@@ -905,6 +905,33 @@
                 "endIndex": 2
               },
               "isStatic": false
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "api-documenter-test!DocClass1#writeonlyProperty:member",
+              "docComment": "/**\n * API Extractor will surface an `ae-missing-getter` finding for this property.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "set writeonlyProperty(value: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ");"
+                }
+              ],
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "writeonlyProperty",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false
             }
           ],
           "extendsTokenRange": {

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
@@ -49,6 +49,7 @@ export class DocClass1 extends DocBaseClass implements IDocInterface1, IDocInter
     // (undocumented)
     get writeableProperty(): string;
     set writeableProperty(value: string);
+    set writeonlyProperty(value: string);
 }
 
 // @public

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
@@ -38,6 +38,7 @@ The constructor for this class is marked as internal. Third-party code should no
 |  [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. |
 |  [writeableProperty](./api-documenter-test.docclass1.writeableproperty.md) |  | string |  |
+|  [writeonlyProperty](./api-documenter-test.docclass1.writeonlyproperty.md) |  | string | API Extractor will surface an <code>ae-missing-getter</code> finding for this property. |
 
 ## Methods
 

diff --git a/...documenter-test/etc/markdown/api-documenter-test.docclass1.writeonlyproperty.md b/...documenter-test/etc/markdown/api-documenter-test.docclass1.writeonlyproperty.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [api-documenter-test](./api-documenter-test.md) &gt; [DocClass1](./api-documenter-test.docclass1.md) &gt; [writeonlyProperty](./api-documenter-test.docclass1.writeonlyproperty.md)
+
+## DocClass1.writeonlyProperty property
+
+API Extractor will surface an `ae-missing-getter` finding for this property.
+
+<b>Signature:</b>
+
+```typescript
+set writeonlyProperty(value: string);
+```
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
@@ -61,6 +61,19 @@ properties:
         set writeableProperty(value: string);
       return:
         type: string
+  - name: writeonlyProperty
+    uid: 'api-documenter-test!DocClass1#writeonlyProperty:member'
+    package: api-documenter-test!
+    fullName: writeonlyProperty
+    summary: API Extractor will surface an `ae-missing-getter` finding for this property.
+    remarks: ''
+    example: []
+    isPreview: false
+    isDeprecated: false
+    syntax:
+      content: 'set writeonlyProperty(value: string);'
+      return:
+        type: string
 methods:
   - name: deprecatedExample()
     uid: 'api-documenter-test!DocClass1#deprecatedExample:member(1)'

diff --git a/build-tests/api-documenter-test/src/DocClass1.ts b/build-tests/api-documenter-test/src/DocClass1.ts
@@ -206,6 +206,11 @@ export class DocClass1 extends DocBaseClass implements IDocInterface1, IDocInter
   }
   public set writeableProperty(value: string) {}
 
+  /**
+   * API Extractor will surface an `ae-missing-getter` finding for this property.
+   */
+  public set writeonlyProperty(value: string) {}
+
   /**
    * This event is fired whenever the object is modified.
    * @eventProperty

diff --git a/common/changes/@microsoft/api-extractor/handle-setters_2022-05-05-17-41.json b/common/changes/@microsoft/api-extractor/handle-setters_2022-05-05-17-41.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "comment": "Generate API doc model nodes for setters without getters",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor"
+}