Merge pull request #945 from Microsoft/pgonzal/ae-variable-declaraitons

[api-extractor] Fix an issue where .d.ts trimming did not work for exported variable declaration

apps/api-extractor/src/generators/dtsRollup/DtsRollupGenerator.ts

@@ -486,9 +486,33 @@ export class DtsRollupGenerator {
   // In the near future we will overhaul the AEDoc parser to separate syntactic/semantic analysis,
   // at which point this will be wired up to the same ApiDocumentation layer used for the API Review files
   private _getReleaseTagForDeclaration(declaration: ts.Node): ReleaseTag {
+    let nodeForComment: ts.Node = declaration;
+
+    if (ts.isVariableDeclaration(declaration)) {
+      // Variable declarations are special because they can be combined into a list.  For example:
+      //
+      // /** A */ export /** B */ const /** C */ x = 1, /** D **/ [ /** E */ y, z] = [3, 4];
+      //
+      // The compiler will only emit comments A and C in the .d.ts file, so in general there isn't a well-defined
+      // way to document these parts.  API Extractor requires you to break them into separate exports like this:
+      //
+      // /** A */ export const x = 1;
+      //
+      // But _getReleaseTagForDeclaration() still receives a node corresponding to "x", so we need to walk upwards
+      // and find the containing statement in order for getJSDocCommentRanges() to read the comment that we expect.
+      const statement: ts.VariableStatement | undefined = TypeScriptHelpers.findFirstParent(declaration,
+        ts.SyntaxKind.VariableStatement) as ts.VariableStatement | undefined;
+      if (statement !== undefined) {
+        // For a compound declaration, fall back to looking for C instead of A
+        if (statement.declarationList.declarations.length === 1) {
+          nodeForComment = statement;
+        }
+      }
+    }
+
     const sourceFileText: string = declaration.getSourceFile().text;
 
-    for (const commentRange of TypeScriptHelpers.getJSDocCommentRanges(declaration, sourceFileText) || []) {
+    for (const commentRange of TypeScriptHelpers.getJSDocCommentRanges(nodeForComment, sourceFileText) || []) {
       // NOTE: This string includes "/**"
       const commentTextRange: tsdoc.TextRange = tsdoc.TextRange.fromStringRange(
         sourceFileText, commentRange.pos, commentRange.end);

build-tests/api-extractor-test-01/dist/beta/api-extractor-test-01.d.ts

@@ -226,6 +226,8 @@ export declare class TypeReferencesInAedoc {
 
 declare const unexportedCustomSymbol: unique symbol;
 
+/* Excluded from this release type: VARIABLE */
+
 /**
  * Example decorator
  * @public

build-tests/api-extractor-test-01/dist/internal/api-extractor-test-01.d.ts

@@ -246,6 +246,8 @@ export declare class TypeReferencesInAedoc {
 
 declare const unexportedCustomSymbol: unique symbol;
 
+export declare const VARIABLE: string;
+
 /**
  * Example decorator
  * @public

build-tests/api-extractor-test-01/dist/public/api-extractor-test-01.d.ts

@@ -219,6 +219,8 @@ export declare class TypeReferencesInAedoc {
 
 declare const unexportedCustomSymbol: unique symbol;
 
+/* Excluded from this release type: VARIABLE */
+
 /**
  * Example decorator
  * @public

build-tests/api-extractor-test-01/etc/api-extractor-test-01.api.ts

@@ -119,3 +119,4 @@ class TypeReferencesInAedoc {
 export function virtual(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<any>): void;
 
 // WARNING: Unsupported export: fullyExportedCustomSymbol
+// WARNING: Unsupported export: VARIABLE

build-tests/api-extractor-test-01/src/index.ts

@@ -107,3 +107,5 @@ export { default as IInterfaceAsDefaultExport } from './IInterfaceAsDefaultExpor
 export { ReexportedClass3 as ReexportedClass } from './ReexportedClass3/ReexportedClass3';
 
 export { TypeReferencesInAedoc } from './TypeReferencesInAedoc';
+
+export { VARIABLE } from './variableDeclarations';

build-tests/api-extractor-test-01/src/variableDeclarations.ts

@@ -0,0 +1,5 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+/** @alpha */
+export const VARIABLE: string = 'hello';

build-tests/api-extractor-test-04/dist/public/api-extractor-test-04.d.ts

@@ -50,4 +50,4 @@ export declare class PublicClass {
 
 /* Excluded from this release type: RegularEnum */
 
-export declare const variableDeclaration: string;
+/* Excluded from this release type: variableDeclaration */

common/changes/@microsoft/api-extractor/pgonzal-ae-variable-declaraitons_2018-11-15-09-01.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "comment": "Fix an issue where .d.ts trimming did not work for exported variable declarations (GitHub #936)",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor",
+  "email": "pgonzal@users.noreply.github.com"
+}