Introduce a concept of "ancillary" declarations, and make property setters ancillary to getters

octogonz · octogonz · commit dea9b87ed7ed · 2019-11-25T16:09:24.000+09:00
diff --git a/apps/api-extractor/src/analyzer/AstDeclaration.ts b/apps/api-extractor/src/analyzer/AstDeclaration.ts
@@ -234,6 +234,8 @@ export class AstDeclaration {
       case ts.SyntaxKind.EnumDeclaration:
       case ts.SyntaxKind.EnumMember:
       case ts.SyntaxKind.FunctionDeclaration:   // Example: "(x: number): number"
+      case ts.SyntaxKind.GetAccessor:
+      case ts.SyntaxKind.SetAccessor:
       case ts.SyntaxKind.IndexSignature:        // Example: "[key: string]: string"
       case ts.SyntaxKind.InterfaceDeclaration:
       case ts.SyntaxKind.MethodDeclaration:
@@ -245,6 +247,9 @@ export class AstDeclaration {
       case ts.SyntaxKind.VariableDeclaration:
         return true;
 
+      // NOTE: Prior to TypeScript 3.7, in the emitted .d.ts files, the compiler would merge a GetAccessor/SetAccessor
+      // pair into a single PropertyDeclaration.
+
       // NOTE: In contexts where a source file is treated as a module, we do create "nominal analysis"
       // AstSymbol objects corresponding to a ts.SyntaxKind.SourceFile node.  However, a source file
       // is NOT considered a nesting structure, and it does NOT act as a root for the declarations
diff --git a/apps/api-extractor/src/collector/Collector.ts b/apps/api-extractor/src/collector/Collector.ts
@@ -525,6 +525,18 @@ export class Collector {
       if (effectiveReleaseTag > maxEffectiveReleaseTag) {
         maxEffectiveReleaseTag = effectiveReleaseTag;
       }
+
+      // For a getter/setter pair, make the setter ancillary to the getter
+      if (astDeclaration.declaration.kind === ts.SyntaxKind.SetAccessor) {
+        for (const getterAstDeclaration of astDeclaration.astSymbol.astDeclarations) {
+          if (getterAstDeclaration.declaration.kind === ts.SyntaxKind.GetAccessor) {
+            const getterMetadata: DeclarationMetadata = getterAstDeclaration.metadata as DeclarationMetadata;
+
+            // Associate it with the getter
+            getterMetadata.addAncillaryDeclaration(astDeclaration);
+          }
+        }
+      }
     }
 
     const symbolMetadata: SymbolMetadata = new SymbolMetadata();
diff --git a/apps/api-extractor/src/collector/DeclarationMetadata.ts b/apps/api-extractor/src/collector/DeclarationMetadata.ts
@@ -4,6 +4,8 @@
 import * as tsdoc from '@microsoft/tsdoc';
 import { ReleaseTag } from '@microsoft/api-extractor-model';
 import { VisitorState } from './VisitorState';
+import { AstDeclaration } from '../analyzer/AstDeclaration';
+import { InternalError } from '@microsoft/node-core-library';
 
 export class DeclarationMetadata {
   /**
@@ -47,4 +49,41 @@ export class DeclarationMetadata {
   public releaseTagSameAsParent: boolean = false;
 
   public docCommentEnhancerVisitorState: VisitorState = VisitorState.Unvisited;
+
+  /**
+   * If true, then this declaration is treated as part of another declaration.
+   */
+  public isAncillary: boolean = false;
+
+  /**
+   * A list of other declarations that are treated as being part of this declaration.  For example, a property
+   * getter/setter pair will be treated as a single API item, with the setter being treated as ancillary to the getter.
+   *
+   * If the `ancillaryDeclarations` array is non-empty, then `isAncillary` will be false for this declaration,
+   * and `isAncillary` will be true for all the array items.
+   */
+  public ancillaryDeclarations: AstDeclaration[] = [];
+
+  public addAncillaryDeclaration(otherDeclaration: AstDeclaration): void {
+    const otherMetadata: DeclarationMetadata = otherDeclaration.metadata as DeclarationMetadata;
+
+    if (!otherMetadata) {
+      throw new InternalError('addAncillaryDeclaration() cannot be called before the declaration metadata is solved');
+    }
+
+    if (this.ancillaryDeclarations.indexOf(otherDeclaration) >= 0) {
+      return;  // already added
+    }
+
+    if (this.isAncillary) {
+      throw new InternalError('Invalid call to addAncillaryDeclaration() because the target is ancillary itself');
+    }
+
+    if (otherMetadata.isAncillary) {
+      throw new InternalError('Invalid call to addAncillaryDeclaration() because source is already ancillary to another declaration');
+    }
+
+    otherMetadata.isAncillary = true;
+    this.ancillaryDeclarations.push(otherDeclaration);
+  }
 }
diff --git a/apps/api-extractor/src/generators/ApiModelGenerator.ts b/apps/api-extractor/src/generators/ApiModelGenerator.ts
@@ -132,6 +132,10 @@ export class ApiModelGenerator {
         this._processApiFunction(astDeclaration, exportedName, parentApiItem);
         break;
 
+      case ts.SyntaxKind.GetAccessor:
+        this._processApiProperty(astDeclaration, exportedName, parentApiItem);
+        break;
+
       case ts.SyntaxKind.IndexSignature:
         this._processApiIndexSignature(astDeclaration, exportedName, parentApiItem);
         break;
