Skip to content

Commit a05699c

Browse files
sandersnsandersn
authored
Emit @overload comments on generated overloads in.d.ts (#54846)
1 parent b1a96a3 commit a05699c

8 files changed

+262
-0
lines changed

‎src/compiler/checker.ts

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7440,6 +7440,10 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker {
74407440
if (typeArguments) {
74417441
node.typeArguments = factory.createNodeArray(typeArguments);
74427442
}
7443+
if (signature.declaration?.kind === SyntaxKind.JSDocSignature && signature.declaration.parent.kind === SyntaxKind.JSDocOverloadTag) {
7444+
const comment = getTextOfNode(signature.declaration.parent.parent, /*includeTrivia*/ true).slice(2, -2).split(/\r\n|\n|\r/).map(line => line.replace(/^\s+/, " ")).join("\n");
7445+
addSyntheticLeadingComment(node, SyntaxKind.MultiLineCommentTrivia, comment, /*hasTrailingNewLine*/ true);
7446+
}
74437447

74447448
cleanup?.();
74457449
return node;

‎tests/baselines/reference/jsFileFunctionOverloads.js

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,10 +120,39 @@ function flatMap(array, iterable) {
120120

121121

122122
//// [jsFileFunctionOverloads.d.ts]
123+
/**
124+
* @overload
125+
* @param {number} x
126+
* @returns {'number'}
127+
*/
123128
declare function getTypeName(x: number): 'number';
129+
/**
130+
* @overload
131+
* @param {string} x
132+
* @returns {'string'}
133+
*/
124134
declare function getTypeName(x: string): 'string';
135+
/**
136+
* @overload
137+
* @param {boolean} x
138+
* @returns {'boolean'}
139+
*/
125140
declare function getTypeName(x: boolean): 'boolean';
141+
/**
142+
* @template T
143+
* @template U
144+
* @overload
145+
* @param {T[]} array
146+
* @param {(x: T) => U[]} iterable
147+
* @returns {U[]}
148+
*/
126149
declare function flatMap<T, U>(array: T[], iterable: (x: T) => U[]): U[];
150+
/**
151+
* @template T
152+
* @overload
153+
* @param {T[][]} array
154+
* @returns {T[]}
155+
*/
127156
declare function flatMap<T>(array: T[][]): T[];
128157
/**
129158
* @template T

‎tests/baselines/reference/jsFileFunctionOverloads2.js

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,10 +110,90 @@ function flatMap(array, iterable) {
110110

111111

112112
//// [jsFileFunctionOverloads2.d.ts]
113+
/**
114+
* @overload
115+
* @param {number} x
116+
* @returns {'number'}
117+
*
118+
* @overload
119+
* @param {string} x
120+
* @returns {'string'}
121+
*
122+
* @overload
123+
* @param {boolean} x
124+
* @returns {'boolean'}
125+
*
126+
* @param {unknown} x
127+
* @returns {string}
128+
*/
113129
declare function getTypeName(x: number): 'number';
130+
/**
131+
* @overload
132+
* @param {number} x
133+
* @returns {'number'}
134+
*
135+
* @overload
136+
* @param {string} x
137+
* @returns {'string'}
138+
*
139+
* @overload
140+
* @param {boolean} x
141+
* @returns {'boolean'}
142+
*
143+
* @param {unknown} x
144+
* @returns {string}
145+
*/
114146
declare function getTypeName(x: string): 'string';
147+
/**
148+
* @overload
149+
* @param {number} x
150+
* @returns {'number'}
151+
*
152+
* @overload
153+
* @param {string} x
154+
* @returns {'string'}
155+
*
156+
* @overload
157+
* @param {boolean} x
158+
* @returns {'boolean'}
159+
*
160+
* @param {unknown} x
161+
* @returns {string}
162+
*/
115163
declare function getTypeName(x: boolean): 'boolean';
164+
/**
165+
* @template T
166+
* @template U
167+
* @overload
168+
* @param {T[]} array
169+
* @param {(x: T) => U[]} iterable
170+
* @returns {U[]}
171+
*
172+
* @overload
173+
* @param {T[][]} array
174+
* @returns {T[]}
175+
*
176+
* @param {unknown[]} array
177+
* @param {(x: unknown) => unknown} iterable
178+
* @returns {unknown[]}
179+
*/
116180
declare function flatMap<T, U>(array: T[], iterable: (x: T) => U[]): U[];
181+
/**
182+
* @template T
183+
* @template U
184+
* @overload
185+
* @param {T[]} array
186+
* @param {(x: T) => U[]} iterable
187+
* @returns {U[]}
188+
*
189+
* @overload
190+
* @param {T[][]} array
191+
* @returns {T[]}
192+
*
193+
* @param {unknown[]} array
194+
* @param {(x: unknown) => unknown} iterable
195+
* @returns {unknown[]}
196+
*/
117197
declare function flatMap<T, U>(array: T[][]): T[];
118198
/**
119199
* @template T

‎tests/baselines/reference/jsFileMethodOverloads.js

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,8 +107,28 @@ declare class Example<T> {
107107
*/
108108
constructor(value: T);
109109
value: T;
110+
/**
111+
* @overload
112+
* @param {Example<number>} this
113+
* @returns {'number'}
114+
*/
110115
getTypeName(this: Example<number>): 'number';
116+
/**
117+
* @overload
118+
* @param {Example<string>} this
119+
* @returns {'string'}
120+
*/
111121
getTypeName(this: Example<string>): 'string';
122+
/**
123+
* @template U
124+
* @overload
125+
* @param {(y: T) => U} fn
126+
* @returns {U}
127+
*/
112128
transform<U>(fn: (y: T) => U): U;
129+
/**
130+
* @overload
131+
* @returns {T}
132+
*/
113133
transform(): T;
114134
}

‎tests/baselines/reference/jsFileMethodOverloads2.js

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,8 +101,54 @@ declare class Example<T> {
101101
*/
102102
constructor(value: T);
103103
value: T;
104+
/**
105+
* @overload
106+
* @param {Example<number>} this
107+
* @returns {'number'}
108+
*
109+
* @overload
110+
* @param {Example<string>} this
111+
* @returns {'string'}
112+
*
113+
* @returns {string}
114+
*/
104115
getTypeName(this: Example<number>): 'number';
116+
/**
117+
* @overload
118+
* @param {Example<number>} this
119+
* @returns {'number'}
120+
*
121+
* @overload
122+
* @param {Example<string>} this
123+
* @returns {'string'}
124+
*
125+
* @returns {string}
126+
*/
105127
getTypeName(this: Example<string>): 'string';
128+
/**
129+
* @template U
130+
* @overload
131+
* @param {(y: T) => U} fn
132+
* @returns {U}
133+
*
134+
* @overload
135+
* @returns {T}
136+
*
137+
* @param {(y: T) => unknown} [fn]
138+
* @returns {unknown}
139+
*/
106140
transform<U>(fn: (y: T) => U): U;
141+
/**
142+
* @template U
143+
* @overload
144+
* @param {(y: T) => U} fn
145+
* @returns {U}
146+
*
147+
* @overload
148+
* @returns {T}
149+
*
150+
* @param {(y: T) => unknown} [fn]
151+
* @returns {unknown}
152+
*/
107153
transform<U>(): T;
108154
}

‎tests/baselines/reference/overloadTag1.js

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,59 @@ uncheckedInternally("zero", "one");
9898

9999

100100
//// [overloadTag1.d.ts]
101+
/**
102+
* @overload
103+
* @param {number} a
104+
* @param {number} b
105+
* @returns {number}
106+
*
107+
* @overload
108+
* @param {string} a
109+
* @param {boolean} b
110+
* @returns {string}
111+
*
112+
* @param {string | number} a
113+
* @param {string | number} b
114+
* @returns {string | number}
115+
*/
101116
export function overloaded(a: number, b: number): number;
117+
/**
118+
* @overload
119+
* @param {number} a
120+
* @param {number} b
121+
* @returns {number}
122+
*
123+
* @overload
124+
* @param {string} a
125+
* @param {boolean} b
126+
* @returns {string}
127+
*
128+
* @param {string | number} a
129+
* @param {string | number} b
130+
* @returns {string | number}
131+
*/
102132
export function overloaded(a: string, b: boolean): string;
133+
/**
134+
* @overload
135+
* @param {number} a
136+
* @param {number} b
137+
* @returns {number}
138+
*
139+
* @overload
140+
* @param {string} a
141+
* @param {boolean} b
142+
* @returns {string}
143+
*/
103144
export function uncheckedInternally(a: number, b: number): number;
145+
/**
146+
* @overload
147+
* @param {number} a
148+
* @param {number} b
149+
* @returns {number}
150+
*
151+
* @overload
152+
* @param {string} a
153+
* @param {boolean} b
154+
* @returns {string}
155+
*/
104156
export function uncheckedInternally(a: string, b: boolean): string;

‎tests/baselines/reference/overloadTag2.js

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,8 +73,25 @@ var d = new Foo('str', 2);
7373

7474
//// [overloadTag2.d.ts]
7575
export class Foo {
76+
/**
77+
* Should not have an implicit any error, because constructor's return type is always implicit
78+
* @constructor
79+
* @overload
80+
* @param {string} a
81+
* @param {number} b
82+
*/
7683
constructor(a: string, b: number);
84+
/**
85+
* @constructor
86+
* @overload
87+
* @param {number} a
88+
*/
7789
constructor(a: number);
90+
/**
91+
* @constructor
92+
* @overload
93+
* @param {string} a
94+
*/
7895
constructor(a: string);
7996
#private;
8097
}

‎tests/baselines/reference/templateInsideCallback.js

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,21 @@ function flatMap(array, iterable) {
114114

115115

116116
//// [templateInsideCallback.d.ts]
117+
/**
118+
* @overload
119+
* @template T
120+
* @template U
121+
* @param {T[]} array
122+
* @param {(x: T) => U[]} iterable
123+
* @returns {U[]}
124+
*/
117125
declare function flatMap<U>(): any;
126+
/**
127+
* @overload
128+
* @template T
129+
* @param {T[][]} array
130+
* @returns {T[]}
131+
*/
118132
declare function flatMap(): any;
119133
/**
120134
* @typedef Oops

0 commit comments

Comments
 (0)