Initial commit

microsoft · Jun 25, 2022 · 33ad56e · 33ad56e
1 parent 67963a1
commit 33ad56e
Show file tree

Hide file tree

Showing 13 changed files with 218 additions and 23 deletions.
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -5,10 +5,12 @@
 			"name": "Rush Debug",
 			"type": "node",
 			"request": "launch",
-			"program": "${workspaceRoot}/apps/rush/lib/start-dev.js",
+			"program": "${workspaceRoot}/libraries/rush-lib/lib/start.js",
 			"stopOnEntry": true,
 			"args": [
-				"start"
+				"rebuild",
+				"-o",
+				"api-extractor-scenarios"
 			],
 			"cwd": "${workspaceRoot}",
 			"runtimeExecutable": null,

diff --git a/apps/api-extractor/src/generators/ApiModelGenerator.ts b/apps/api-extractor/src/generators/ApiModelGenerator.ts
@@ -829,25 +829,29 @@ export class ApiModelGenerator {
     let apiProperty: ApiProperty | undefined = parentApiItem.tryGetMemberByKey(containerKey) as ApiProperty;
 
     if (apiProperty === undefined) {
+      const declaration: ts.Declaration = astDeclaration.declaration;
       const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];
 
       const propertyTypeTokenRange: IExcerptTokenRange = ExcerptBuilder.createEmptyTokenRange();
       let propertyTypeNode: ts.TypeNode | undefined;
 
-      if (
-        ts.isPropertyDeclaration(astDeclaration.declaration) ||
-        ts.isGetAccessorDeclaration(astDeclaration.declaration)
-      ) {
-        propertyTypeNode = astDeclaration.declaration.type;
+      if (ts.isPropertyDeclaration(declaration) || ts.isGetAccessorDeclaration(declaration)) {
+        propertyTypeNode = declaration.type;
       }
 
-      if (ts.isSetAccessorDeclaration(astDeclaration.declaration)) {
+      if (ts.isSetAccessorDeclaration(declaration)) {
         // Note that TypeScript always reports an error if a setter does not have exactly one parameter.
-        propertyTypeNode = astDeclaration.declaration.parameters[0].type;
+        propertyTypeNode = declaration.parameters[0].type;
       }
 
       nodesToCapture.push({ node: propertyTypeNode, tokenRange: propertyTypeTokenRange });
 
+      let initializerTokenRange: IExcerptTokenRange | undefined = undefined;
+      if (ts.isPropertyDeclaration(declaration) && declaration.initializer) {
+        initializerTokenRange = ExcerptBuilder.createEmptyTokenRange();
+        nodesToCapture.push({ node: declaration.initializer, tokenRange: initializerTokenRange });
+      }
+
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
       const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
@@ -866,7 +870,8 @@ export class ApiModelGenerator {
         isOptional,
         isReadonly,
         excerptTokens,
-        propertyTypeTokenRange
+        propertyTypeTokenRange,
+        initializerTokenRange
       });
       parentApiItem.addMember(apiProperty);
     } else {
@@ -985,6 +990,12 @@ export class ApiModelGenerator {
       const variableTypeTokenRange: IExcerptTokenRange = ExcerptBuilder.createEmptyTokenRange();
       nodesToCapture.push({ node: variableDeclaration.type, tokenRange: variableTypeTokenRange });
 
+      let initializerTokenRange: IExcerptTokenRange | undefined = undefined;
+      if (variableDeclaration.initializer) {
+        initializerTokenRange = ExcerptBuilder.createEmptyTokenRange();
+        nodesToCapture.push({ node: variableDeclaration.initializer, tokenRange: initializerTokenRange });
+      }
+
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
       const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
       const docComment: tsdoc.DocComment | undefined = apiItemMetadata.tsdocComment;
@@ -997,6 +1008,7 @@ export class ApiModelGenerator {
         releaseTag,
         excerptTokens,
         variableTypeTokenRange,
+        initializerTokenRange,
         isReadonly
       });
 

diff --git a/...ts/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json b/...ts/api-extractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.json
@@ -322,6 +322,28 @@
           ],
           "implementsTokenRanges": []
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "api-extractor-scenarios!CONST_VARIABLE:var",
+          "docComment": "/**\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "CONST_VARIABLE: "
+            },
+            {
+              "kind": "Content",
+              "text": "string"
+            }
+          ],
+          "isReadonly": true,
+          "releaseTag": "Public",
+          "name": "CONST_VARIABLE",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
         {
           "kind": "Enum",
           "canonicalReference": "api-extractor-scenarios!ConstEnum:enum",
@@ -505,6 +527,28 @@
             }
           ]
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "api-extractor-scenarios!nonConstVariable:var",
+          "docComment": "/**\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "nonConstVariable: "
+            },
+            {
+              "kind": "Content",
+              "text": "string"
+            }
+          ],
+          "isReadonly": false,
+          "releaseTag": "Public",
+          "name": "nonConstVariable",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
         {
           "kind": "Enum",
           "canonicalReference": "api-extractor-scenarios!RegularEnum:enum",
@@ -711,7 +755,15 @@
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "readonly someReadonlyProp = 5;"
+                  "text": "readonly someReadonlyProp = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "5"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
                 }
               ],
               "isReadonly": true,
@@ -723,7 +775,11 @@
                 "endIndex": 0
               },
               "isStatic": false,
-              "isProtected": false
+              "isProtected": false,
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
             },
             {
               "kind": "Property",
@@ -792,22 +848,26 @@
         },
         {
           "kind": "Variable",
-          "canonicalReference": "api-extractor-scenarios!VARIABLE:var",
+          "canonicalReference": "api-extractor-scenarios!VARIABLE_WITHOUT_EXPLICIT_TYPE:var",
           "docComment": "/**\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
-              "text": "VARIABLE: "
+              "text": "VARIABLE_WITHOUT_EXPLICIT_TYPE = "
             },
             {
               "kind": "Content",
-              "text": "string"
+              "text": "\"hello\""
             }
           ],
           "isReadonly": true,
           "releaseTag": "Public",
-          "name": "VARIABLE",
+          "name": "VARIABLE_WITHOUT_EXPLICIT_TYPE",
           "variableTypeTokenRange": {
+            "startIndex": 0,
+            "endIndex": 0
+          },
+          "initializerTokenRange": {
             "startIndex": 1,
             "endIndex": 2
           }

diff --git a/...xtractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.md b/...xtractor-scenarios/etc/test-outputs/apiItemKinds/api-extractor-scenarios.api.md
@@ -22,6 +22,9 @@ export class ClassWithTypeLiterals {
     } | undefined;
 }
 
+// @public (undocumented)
+export const CONST_VARIABLE: string;
+
 // @public (undocumented)
 export const enum ConstEnum {
     // (undocumented)
@@ -46,6 +49,9 @@ export namespace NamespaceContainingVariable {
     constVariable: object[];
 }
 
+// @public (undocumented)
+export let nonConstVariable: string;
+
 // @public (undocumented)
 export enum RegularEnum {
     One = 1,
@@ -71,7 +77,7 @@ export class SimpleClass {
 }
 
 // @public (undocumented)
-export const VARIABLE: string;
+export const VARIABLE_WITHOUT_EXPLICIT_TYPE = "hello";
 
 // (No @packageDocumentation comment for this package)
 

diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/test-outputs/apiItemKinds/rollup.d.ts
@@ -17,6 +17,9 @@ export declare class ClassWithTypeLiterals {
     } | undefined;
 }
 
+/** @public */
+export declare const CONST_VARIABLE: string;
+
 /** @public */
 export declare const enum ConstEnum {
     Zero = 0,
@@ -35,6 +38,9 @@ export declare namespace NamespaceContainingVariable {
     let constVariable: object[];
 }
 
+/** @public */
+export declare let nonConstVariable: string;
+
 /** @public */
 export declare enum RegularEnum {
     /**
@@ -63,6 +69,6 @@ export declare class SimpleClass {
 }
 
 /** @public */
-export declare const VARIABLE: string;
+export declare const VARIABLE_WITHOUT_EXPLICIT_TYPE = "hello";
 
 export { }
diff --git a/...xtractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json b/...xtractor-scenarios/etc/test-outputs/readonlyDeclarations/api-extractor-scenarios.api.json
@@ -223,7 +223,11 @@
           "excerptTokens": [
             {
               "kind": "Content",
-              "text": "FOO = \"foo\""
+              "text": "FOO = "
+            },
+            {
+              "kind": "Content",
+              "text": "\"foo\""
             }
           ],
           "isReadonly": true,
@@ -232,6 +236,10 @@
           "variableTypeTokenRange": {
             "startIndex": 0,
             "endIndex": 0
+          },
+          "initializerTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
           }
         },
         {

diff --git a/build-tests/api-extractor-scenarios/src/apiItemKinds/variables.ts b/build-tests/api-extractor-scenarios/src/apiItemKinds/variables.ts
@@ -2,7 +2,13 @@
 // See LICENSE in the project root for license information.
 
 /** @public */
-export const VARIABLE: string = 'hello';
+export const CONST_VARIABLE: string = 'hello';
+
+/** @public */
+export let nonConstVariable: string = 'hello';
+
+/** @public */
+export const VARIABLE_WITHOUT_EXPLICIT_TYPE = 'hello';
 
 /** @public */
 export namespace NamespaceContainingVariable {

diff --git a/common/changes/@microsoft/api-extractor-model/initializer_2022-06-18-13-49.json b/common/changes/@microsoft/api-extractor-model/initializer_2022-06-18-13-49.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor-model",
+      "comment": "Add a new initializerTokenRange field to ApiProperty and ApiVariable items.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor-model"
+}
diff --git a/common/changes/@microsoft/api-extractor/initializer_2022-06-18-13-49.json b/common/changes/@microsoft/api-extractor/initializer_2022-06-18-13-49.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "comment": "API Extractor now populates an initializerTokenRange field for ApiProperty and ApiVariable items.",
+      "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
@@ -476,8 +476,15 @@ export class ApiProperty extends ApiProperty_base {
     get containerKey(): string;
     // (undocumented)
     static getContainerKey(name: string, isStatic: boolean): string;
+    readonly initializerExcerpt: Excerpt | undefined;
     // @override (undocumented)
     get kind(): ApiItemKind;
+    // Warning: (ae-forgotten-export) The symbol "IApiPropertyJson" needs to be exported by the entry point index.d.ts
+    //
+    // @override (undocumented)
+    static onDeserializeInto(options: Partial<IApiPropertyOptions>, context: DeserializerContext, jsonObject: IApiPropertyJson): void;
+    // @override (undocumented)
+    serializeInto(jsonObject: Partial<IApiPropertyJson>): void;
 }
 
 // Warning: (ae-forgotten-export) The symbol "ApiPropertyItem_base" needs to be exported by the entry point index.d.ts
@@ -633,6 +640,7 @@ export class ApiVariable extends ApiVariable_base {
     get containerKey(): string;
     // (undocumented)
     static getContainerKey(name: string): string;
+    readonly initializerExcerpt?: Excerpt;
     // @override (undocumented)
     get kind(): ApiItemKind;
     // Warning: (ae-forgotten-export) The symbol "IApiVariableJson" needs to be exported by the entry point index.d.ts
@@ -822,6 +830,8 @@ export interface IApiPropertyItemOptions extends IApiNameMixinOptions, IApiRelea
 
 // @public
 export interface IApiPropertyOptions extends IApiPropertyItemOptions, IApiProtectedMixinOptions, IApiStaticMixinOptions {
+    // (undocumented)
+    initializerTokenRange?: IExcerptTokenRange;
 }
 
 // @public
@@ -882,6 +892,8 @@ export interface IApiTypeParameterOptions {
 
 // @public
 export interface IApiVariableOptions extends IApiNameMixinOptions, IApiReleaseTagMixinOptions, IApiReadonlyMixinOptions, IApiDeclaredItemOptions {
+    // (undocumented)
+    initializerTokenRange?: IExcerptTokenRange;
     // (undocumented)
     variableTypeTokenRange: IExcerptTokenRange;
 }