preserve comments on signatures and declarations where possible

Author: weswigham

src/compiler/checker.ts

@@ -4959,6 +4959,7 @@ namespace ts {
                             createNamedExports(flatMap(exports, e => e.exportClause!.elements)),
                             /*moduleSpecifier*/ undefined
                         )];
+                        // TODO combine multiple `export {a} from "..."` into a single statement
                     }
                     // Pass 3: Move all `export {}`'s to `export` modifiers where possible
                     const exportDecl = find(statements, d => isExportDeclaration(d) && !d.moduleSpecifier && !!d.exportClause) as ExportDeclaration | undefined;
@@ -5091,7 +5092,7 @@ namespace ts {
                         // Each overload becomes a seperate function declaration, in order
                         const decl = signatureToSignatureDeclarationHelper(sig, SyntaxKind.FunctionDeclaration, context) as FunctionDeclaration;
                         decl.name = createIdentifier(localName);
-                        addResult(decl, modifierFlags);
+                        addResult(setTextRange(decl, sig.declaration), modifierFlags);
                     }
                     const props = getPropertiesOfType(type);
                     if (length(props)) {
@@ -5142,14 +5143,14 @@ namespace ts {
                         c.typeParameters = undefined;
                     }
                     const indexSignatures = serializeIndexSignatures(classType, baseTypes[0]);
-                    addResult(createClassDeclaration(
+                    addResult(setTextRange(createClassDeclaration(
                         /*decorators*/ undefined,
                         /*modifiers*/ undefined,
                         localName,
                         typeParamDecls,
                         heritageClauses,
                         [...indexSignatures, ...staticMembers, ...constructors, ...members]
-                    ), modifierFlags);
+                    ), filter(symbol.declarations, d => isClassDeclaration(d) || isClassExpression(d))[0]), modifierFlags);
                 }
 
                 // Synthesize declarations for a symbol - might be an Interface, a Class, a Namespace, a Type, a Variable (const, let, or var), an Alias
@@ -5200,9 +5201,13 @@ namespace ts {
                         // `var` is `FunctionScopedVariable`, `const` and `let` are `BlockScopedVariable`, and `module.exports.thing =` is `Property`
                         const flags = !(symbol.flags & SymbolFlags.BlockScopedVariable) ? undefined : isConstVariable(symbol) ? NodeFlags.Const : NodeFlags.Let;
                         const name = (needsPostExportDefault || !(symbol.flags & SymbolFlags.Property)) ? localName : getUnusedName(localName, symbol);
-                        const statement = createVariableStatement(/*modifiers*/ undefined, createVariableDeclarationList([
+                        let textRange: Node | undefined = filter(symbol.declarations, d => isVariableDeclaration(d))[0];
+                        if (textRange && isVariableDeclarationList(textRange.parent) && textRange.parent.declarations.length === 1) {
+                            textRange = textRange.parent.parent;
+                        }
+                        const statement = setTextRange(createVariableStatement(/*modifiers*/ undefined, createVariableDeclarationList([
                             createVariableDeclaration(name, serializeTypeForDeclaration(getTypeOfSymbol(symbol), symbol))
-                        ], flags));
+                        ], flags)), textRange);
                         addResult(statement, name !== localName ? modifierFlags & ~ModifierFlags.Export : modifierFlags);
                         if (name !== localName && !isPrivate) {
                             // We rename the variable declaration we generate for Property symbols since they may have a name which conflicts with a local declaration. Eg,
@@ -5338,7 +5343,8 @@ namespace ts {
                                 break;
                             case SyntaxKind.ExportSpecifier:
                                 // does not use localName because the symbol name in this case refers to the name in the exports table, which we must exactly preserve
-                                serializeExportSpecifier(unescapeLeadingUnderscores(symbol.escapedName), targetName);
+                                const specifier = (node.parent.parent as ExportDeclaration).moduleSpecifier;
+                                serializeExportSpecifier(unescapeLeadingUnderscores(symbol.escapedName), targetName, specifier && isStringLiteralLike(specifier) ? createLiteral(specifier.text) : undefined);
                                 break;
                             case SyntaxKind.ExportAssignment:
                                 serializeMaybeAliasAssignment(symbol);
@@ -5362,8 +5368,13 @@ namespace ts {
                     }
                 }
 
-                function serializeExportSpecifier(localName: string, targetName: string) {
-                    addResult(createExportDeclaration(/*decorators*/ undefined, /*modifiers*/ undefined, createNamedExports([createExportSpecifier(localName !== targetName ? targetName : undefined, localName)])), ModifierFlags.None);
+                function serializeExportSpecifier(localName: string, targetName: string, specifier?: Expression) {
+                    addResult(createExportDeclaration(
+                        /*decorators*/ undefined,
+                        /*modifiers*/ undefined,
+                        createNamedExports([createExportSpecifier(localName !== targetName ? targetName : undefined, localName)]),
+                        specifier
+                    ), ModifierFlags.None);
                 }
 
                 function serializeMaybeAliasAssignment(symbol: Symbol) {
@@ -5485,14 +5496,14 @@ namespace ts {
                         const rawName = unescapeLeadingUnderscores(p.escapedName);
                         const name = getPropertyNameNodeForSymbolFromNameType(p, context) || createIdentifier(rawName);
                         if (p.flags & (SymbolFlags.Property | SymbolFlags.Accessor | SymbolFlags.Variable)) {
-                            return createProperty(
+                            return setTextRange(createProperty(
                                 /*decorators*/ undefined,
                                 createModifiersFromModifierFlags((isReadonlySymbol(p) ? ModifierFlags.Readonly : 0) | staticFlag),
                                 name,
                                 p.flags & SymbolFlags.Optional ? createToken(SyntaxKind.QuestionToken) : undefined,
                                 serializeTypeForDeclaration(getTypeOfSymbol(p), p),
                                 /*initializer*/ undefined // interface members can't have initializers, however class members _can_
-                            );
+                            ), filter(p.declarations, d => isPropertyDeclaration(d) || isAccessor(d) || isVariableDeclaration(d) || isPropertySignature(d) || isBinaryExpression(d) || isPropertyAccessExpression(d))[0]);
                         }
                         if (p.flags & (SymbolFlags.Method | SymbolFlags.Function)) {
                             const type = getTypeOfSymbol(p);
@@ -5508,7 +5519,7 @@ namespace ts {
                                 if (p.flags & SymbolFlags.Optional) {
                                     decl.questionToken = createToken(SyntaxKind.QuestionToken);
                                 }
-                                results.push(decl);
+                                results.push(setTextRange(decl, sig.declaration));
                             }
                             return results as unknown as T[];
                         }
@@ -5695,7 +5706,7 @@ namespace ts {
                     for (const sig of signatures) {
                         // Each overload becomes a seperate constructor declaration, in order
                         const decl = signatureToSignatureDeclarationHelper(sig, outputKind, context);
-                        results.push(decl);
+                        results.push(setTextRange(decl, sig.declaration));
                     }
                     return results;
                 }

tests/baselines/reference/jsDeclarationsClasses.js

@@ -459,26 +459,84 @@ export class C {
     };
 }
 export class D {
+    /**
+     * @param {number} a
+     * @param {number} b
+     */
     constructor(a: number, b: number);
 }
+/**
+ * @template T,U
+ */
 export class E<T, U> {
+    /**
+     * @type {string}
+     */
     static staticField: string;
+    /**
+     * @type {string}
+     * @readonly
+     */
     static staticReadonlyField: string;
     static staticInitializedField: number;
+    /**
+     * @return {string}
+     */
     static s1: string;
+    /**
+     * @return {string}
+     */
     static readonly s2: string;
+    /**
+     * @param {string} _p
+     */
     static s3: string;
+    /**
+     * @param {T} a
+     * @param {U} b
+     */
     constructor(a: T, b: U);
+    /**
+     * @type {T & U}
+     */
     field: T & U;
+    /**
+     * @type {T & U}
+     * @readonly
+     */
     readonlyField: T & U;
     initializedField: number;
+    /**
+     * @return {U}
+     */
     f1: U;
+    /**
+     * @return {U}
+     */
     readonly f2: U;
+    /**
+     * @param {U} _p
+     */
     f3: U;
 }
+/**
+ * @template T,U
+ */
 export class F<T, U> {
+    /**
+     * @template A,B
+     * @param {A} a
+     * @param {B} b
+     */
     static create<A_1, B_1>(a: A_1, b: B_1): F<A_1, B_1>;
+    /**
+     * @param {T} a
+     * @param {U} b
+     */
     constructor(a: T, b: U);
+    /**
+     * @type {T & U}
+     */
     field: T & U;
 }
 export class I {
@@ -495,11 +553,24 @@ export class L extends K {
 export class M {
     prop: number;
 }
+/**
+ * @template T
+ */
 export class N<T> extends L {
+    /**
+     * @param {T} param
+     */
     constructor(param: T);
     another: T;
 }
+/**
+ * @template U
+ * @extends {N<U>}
+ */
 export class O<U> extends N<U> {
+    /**
+     * @param {U} param
+     */
     constructor(param: U);
     another2: U;
 }

tests/baselines/reference/jsDeclarationsComputedNames.js

@@ -81,6 +81,9 @@ declare const InnerSym: unique symbol;
 //// [index2.d.ts]
 export class MyClass {
     static [TopLevelSym]: number;
+    /**
+     * @param {typeof TopLevelSym | typeof InnerSym} _p
+     */
     constructor(_p?: typeof TopLevelSym | typeof InnerSym);
     [InnerSym]: string;
 }

tests/baselines/reference/jsDeclarationsEnumTag.js

@@ -102,7 +102,13 @@ exports.ff = ff;
 
 
 //// [index.d.ts]
+/**
+ * @param {Target} t
+ * @param {Second} s
+ * @param {Fs} f
+ */
 export function consume(t: string, s: number, f: (arg0: number) => number): void;
+/** @param {string} s */
 export function ff(s: string): any;
 export type Target = string;
 export const Target: {

tests/baselines/reference/jsDeclarationsExportAssignedClassExpression.js

@@ -23,6 +23,9 @@ module.exports = /** @class */ (function () {
 //// [index.d.ts]
 export = Thing;
 declare class Thing {
+    /**
+     * @param {number} p
+     */
     constructor(p: number);
     t: number;
 }

tests/baselines/reference/jsDeclarationsExportAssignedClassExpressionAnonymous.js

@@ -23,6 +23,9 @@ module.exports = /** @class */ (function () {
 //// [index.d.ts]
 export = exports;
 declare class exports {
+    /**
+     * @param {number} p
+     */
     constructor(p: number);
     t: number;
 }

tests/baselines/reference/jsDeclarationsExportAssignedClassExpressionAnonymousWithSub.js

@@ -35,6 +35,9 @@ module.exports.Sub = /** @class */ (function () {
 //// [index.d.ts]
 export = exports;
 declare class exports {
+    /**
+     * @param {number} p
+     */
     constructor(p: number);
     t: number;
 }

tests/baselines/reference/jsDeclarationsExportSpecifierNonlocal.js

@@ -0,0 +1,40 @@
+//// [tests/cases/conformance/jsdoc/declarations/jsDeclarationsExportSpecifierNonlocal.ts] ////
+
+//// [source.js]
+export class Thing {}
+export class OtherThing {}
+//// [index.js]
+export { Thing, OtherThing as default } from "./source";
+
+
+//// [source.js]
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var Thing = /** @class */ (function () {
+    function Thing() {
+    }
+    return Thing;
+}());
+exports.Thing = Thing;
+var OtherThing = /** @class */ (function () {
+    function OtherThing() {
+    }
+    return OtherThing;
+}());
+exports.OtherThing = OtherThing;
+//// [index.js]
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var source_1 = require("./source");
+exports.Thing = source_1.Thing;
+exports.default = source_1.OtherThing;
+
+
+//// [source.d.ts]
+export class Thing {
+}
+export class OtherThing {
+}
+//// [index.d.ts]
+export { Thing } from "./source";
+export { OtherThing as default } from "./source";

tests/baselines/reference/jsDeclarationsExportSpecifierNonlocal.symbols

@@ -0,0 +1,13 @@
+=== tests/cases/conformance/jsdoc/declarations/source.js ===
+export class Thing {}
+>Thing : Symbol(Thing, Decl(source.js, 0, 0))
+
+export class OtherThing {}
+>OtherThing : Symbol(OtherThing, Decl(source.js, 0, 21))
+
+=== tests/cases/conformance/jsdoc/declarations/index.js ===
+export { Thing, OtherThing as default } from "./source";
+>Thing : Symbol(Thing, Decl(index.js, 0, 8))
+>OtherThing : Symbol(OtherThing, Decl(source.js, 0, 21))
+>default : Symbol(default, Decl(index.js, 0, 15))
+

tests/baselines/reference/jsDeclarationsExportSpecifierNonlocal.types

@@ -0,0 +1,13 @@
+=== tests/cases/conformance/jsdoc/declarations/source.js ===
+export class Thing {}
+>Thing : Thing
+
+export class OtherThing {}
+>OtherThing : OtherThing
+
+=== tests/cases/conformance/jsdoc/declarations/index.js ===
+export { Thing, OtherThing as default } from "./source";
+>Thing : typeof import("tests/cases/conformance/jsdoc/declarations/source").Thing
+>OtherThing : typeof import("tests/cases/conformance/jsdoc/declarations/source").OtherThing
+>default : typeof import("tests/cases/conformance/jsdoc/declarations/source").OtherThing
+