Skip to content

Commit d79657f

Browse files
pgonzalpgonzal
authored
Merge pull request microsoft#945 from Microsoft/pgonzal/ae-variable-declaraitons
[api-extractor] Fix an issue where .d.ts trimming did not work for exported variable declaration
2 parents 261b525 + f8cb577 commit d79657f

10 files changed

Lines changed: 118 additions & 65 deletions

File tree

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

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -486,9 +486,33 @@ export class DtsRollupGenerator {
486486
// In the near future we will overhaul the AEDoc parser to separate syntactic/semantic analysis,
487487
// at which point this will be wired up to the same ApiDocumentation layer used for the API Review files
488488
private _getReleaseTagForDeclaration(declaration: ts.Node): ReleaseTag {
489+
let nodeForComment: ts.Node = declaration;
490+
491+
if (ts.isVariableDeclaration(declaration)) {
492+
// Variable declarations are special because they can be combined into a list. For example:
493+
//
494+
// /** A */ export /** B */ const /** C */ x = 1, /** D **/ [ /** E */ y, z] = [3, 4];
495+
//
496+
// The compiler will only emit comments A and C in the .d.ts file, so in general there isn't a well-defined
497+
// way to document these parts. API Extractor requires you to break them into separate exports like this:
498+
//
499+
// /** A */ export const x = 1;
500+
//
501+
// But _getReleaseTagForDeclaration() still receives a node corresponding to "x", so we need to walk upwards
502+
// and find the containing statement in order for getJSDocCommentRanges() to read the comment that we expect.
503+
const statement: ts.VariableStatement | undefined = TypeScriptHelpers.findFirstParent(declaration,
504+
ts.SyntaxKind.VariableStatement) as ts.VariableStatement | undefined;
505+
if (statement !== undefined) {
506+
// For a compound declaration, fall back to looking for C instead of A
507+
if (statement.declarationList.declarations.length === 1) {
508+
nodeForComment = statement;
509+
}
510+
}
511+
}
512+
489513
const sourceFileText: string = declaration.getSourceFile().text;
490514

491-
for (const commentRange of TypeScriptHelpers.getJSDocCommentRanges(declaration, sourceFileText) || []) {
515+
for (const commentRange of TypeScriptHelpers.getJSDocCommentRanges(nodeForComment, sourceFileText) || []) {
492516
// NOTE: This string includes "/**"
493517
const commentTextRange: tsdoc.TextRange = tsdoc.TextRange.fromStringRange(
494518
sourceFileText, commentRange.pos, commentRange.end);

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -226,6 +226,8 @@ export declare class TypeReferencesInAedoc {
226226

227227
declare const unexportedCustomSymbol: unique symbol;
228228

229+
/* Excluded from this release type: VARIABLE */
230+
229231
/**
230232
* Example decorator
231233
* @public

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -246,6 +246,8 @@ export declare class TypeReferencesInAedoc {
246246

247247
declare const unexportedCustomSymbol: unique symbol;
248248

249+
export declare const VARIABLE: string;
250+
249251
/**
250252
* Example decorator
251253
* @public

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -219,6 +219,8 @@ export declare class TypeReferencesInAedoc {
219219

220220
declare const unexportedCustomSymbol: unique symbol;
221221

222+
/* Excluded from this release type: VARIABLE */
223+
222224
/**
223225
* Example decorator
224226
* @public

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,3 +119,4 @@ class TypeReferencesInAedoc {
119119
export function virtual(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<any>): void;
120120

121121
// WARNING: Unsupported export: fullyExportedCustomSymbol
122+
// WARNING: Unsupported export: VARIABLE

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,3 +107,5 @@ export { default as IInterfaceAsDefaultExport } from './IInterfaceAsDefaultExpor
107107
export { ReexportedClass3 as ReexportedClass } from './ReexportedClass3/ReexportedClass3';
108108

109109
export { TypeReferencesInAedoc } from './TypeReferencesInAedoc';
110+
111+
export { VARIABLE } from './variableDeclarations';

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
2+
// See LICENSE in the project root for license information.
3+
4+
/** @alpha */
5+
export const VARIABLE: string = 'hello';

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,4 +50,4 @@ export declare class PublicClass {
5050

5151
/* Excluded from this release type: RegularEnum */
5252

53-
export declare const variableDeclaration: string;
53+
/* Excluded from this release type: variableDeclaration */

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"changes": [
3+
{
4+
"packageName": "@microsoft/api-extractor",
5+
"comment": "Fix an issue where .d.ts trimming did not work for exported variable declarations (GitHub #936)",
6+
"type": "patch"
7+
}
8+
],
9+
"packageName": "@microsoft/api-extractor",
10+
"email": "pgonzal@users.noreply.github.com"
11+
}

0 commit comments

Comments
 (0)