Emit @overload comments to .d.ts from JS

sandersn · Jun 30, 2023 · 2c4e3da · 2c4e3da
1 parent 34f6e10
commit 2c4e3da
Show file tree

Hide file tree

Showing 8 changed files with 740 additions and 480 deletions.
diff --git a/src/compiler/checker.ts b/src/compiler/checker.ts
diff --git a/tests/baselines/reference/jsFileFunctionOverloads.js b/tests/baselines/reference/jsFileFunctionOverloads.js
@@ -120,10 +120,39 @@ function flatMap(array, iterable) {
 
 
 //// [jsFileFunctionOverloads.d.ts]
+/**
+ * @overload
+ * @param {number} x
+ * @returns {'number'}
+ */
 declare function getTypeName(x: number): 'number';
+/**
+ * @overload
+ * @param {string} x
+ * @returns {'string'}
+ */
 declare function getTypeName(x: string): 'string';
+/**
+ * @overload
+ * @param {boolean} x
+ * @returns {'boolean'}
+ */
 declare function getTypeName(x: boolean): 'boolean';
+/**
+ * @template T
+ * @template U
+ * @overload
+ * @param {T[]} array
+ * @param {(x: T) => U[]} iterable
+ * @returns {U[]}
+ */
 declare function flatMap<T, U>(array: T[], iterable: (x: T) => U[]): U[];
+/**
+ * @template T
+ * @overload
+ * @param {T[][]} array
+ * @returns {T[]}
+ */
 declare function flatMap<T>(array: T[][]): T[];
 /**
  * @template T

diff --git a/tests/baselines/reference/jsFileFunctionOverloads2.js b/tests/baselines/reference/jsFileFunctionOverloads2.js
@@ -110,10 +110,90 @@ function flatMap(array, iterable) {
 
 
 //// [jsFileFunctionOverloads2.d.ts]
+/**
+ * @overload
+ * @param {number} x
+ * @returns {'number'}
+ *
+ * @overload
+ * @param {string} x
+ * @returns {'string'}
+ *
+ * @overload
+ * @param {boolean} x
+ * @returns {'boolean'}
+ *
+ * @param {unknown} x
+ * @returns {string}
+ */
 declare function getTypeName(x: number): 'number';
+/**
+ * @overload
+ * @param {number} x
+ * @returns {'number'}
+ *
+ * @overload
+ * @param {string} x
+ * @returns {'string'}
+ *
+ * @overload
+ * @param {boolean} x
+ * @returns {'boolean'}
+ *
+ * @param {unknown} x
+ * @returns {string}
+ */
 declare function getTypeName(x: string): 'string';
+/**
+ * @overload
+ * @param {number} x
+ * @returns {'number'}
+ *
+ * @overload
+ * @param {string} x
+ * @returns {'string'}
+ *
+ * @overload
+ * @param {boolean} x
+ * @returns {'boolean'}
+ *
+ * @param {unknown} x
+ * @returns {string}
+ */
 declare function getTypeName(x: boolean): 'boolean';
+/**
+ * @template T
+ * @template U
+ * @overload
+ * @param {T[]} array
+ * @param {(x: T) => U[]} iterable
+ * @returns {U[]}
+ *
+ * @overload
+ * @param {T[][]} array
+ * @returns {T[]}
+ *
+ * @param {unknown[]} array
+ * @param {(x: unknown) => unknown} iterable
+ * @returns {unknown[]}
+ */
 declare function flatMap<T, U>(array: T[], iterable: (x: T) => U[]): U[];
+/**
+ * @template T
+ * @template U
+ * @overload
+ * @param {T[]} array
+ * @param {(x: T) => U[]} iterable
+ * @returns {U[]}
+ *
+ * @overload
+ * @param {T[][]} array
+ * @returns {T[]}
+ *
+ * @param {unknown[]} array
+ * @param {(x: unknown) => unknown} iterable
+ * @returns {unknown[]}
+ */
 declare function flatMap<T, U>(array: T[][]): T[];
 /**
  * @template T

diff --git a/tests/baselines/reference/jsFileMethodOverloads.js b/tests/baselines/reference/jsFileMethodOverloads.js
@@ -107,8 +107,28 @@ declare class Example<T> {
      */
     constructor(value: T);
     value: T;
+    /**
+       * @overload
+       * @param {Example<number>} this
+       * @returns {'number'}
+       */
     getTypeName(this: Example<number>): 'number';
+    /**
+       * @overload
+       * @param {Example<string>} this
+       * @returns {'string'}
+       */
     getTypeName(this: Example<string>): 'string';
+    /**
+       * @template U
+       * @overload
+       * @param {(y: T) => U} fn
+       * @returns {U}
+       */
     transform<U>(fn: (y: T) => U): U;
+    /**
+       * @overload
+       * @returns {T}
+       */
     transform(): T;
 }
diff --git a/tests/baselines/reference/jsFileMethodOverloads2.js b/tests/baselines/reference/jsFileMethodOverloads2.js
@@ -101,8 +101,54 @@ declare class Example<T> {
      */
     constructor(value: T);
     value: T;
+    /**
+       * @overload
+       * @param {Example<number>} this
+       * @returns {'number'}
+       *
+       * @overload
+       * @param {Example<string>} this
+       * @returns {'string'}
+       *
+       * @returns {string}
+       */
     getTypeName(this: Example<number>): 'number';
+    /**
+       * @overload
+       * @param {Example<number>} this
+       * @returns {'number'}
+       *
+       * @overload
+       * @param {Example<string>} this
+       * @returns {'string'}
+       *
+       * @returns {string}
+       */
     getTypeName(this: Example<string>): 'string';
+    /**
+       * @template U
+       * @overload
+       * @param {(y: T) => U} fn
+       * @returns {U}
+       *
+       * @overload
+       * @returns {T}
+       *
+       * @param {(y: T) => unknown} [fn]
+       * @returns {unknown}
+       */
     transform<U>(fn: (y: T) => U): U;
+    /**
+       * @template U
+       * @overload
+       * @param {(y: T) => U} fn
+       * @returns {U}
+       *
+       * @overload
+       * @returns {T}
+       *
+       * @param {(y: T) => unknown} [fn]
+       * @returns {unknown}
+       */
     transform<U>(): T;
 }
diff --git a/tests/baselines/reference/overloadTag1.js b/tests/baselines/reference/overloadTag1.js
@@ -98,7 +98,59 @@ uncheckedInternally("zero", "one");
 
 
 //// [overloadTag1.d.ts]
+/**
+ * @overload
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ *
+ * @overload
+ * @param {string} a
+ * @param {boolean} b
+ * @returns {string}
+ *
+ * @param {string | number} a
+ * @param {string | number} b
+ * @returns {string | number}
+ */
 export function overloaded(a: number, b: number): number;
+/**
+ * @overload
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ *
+ * @overload
+ * @param {string} a
+ * @param {boolean} b
+ * @returns {string}
+ *
+ * @param {string | number} a
+ * @param {string | number} b
+ * @returns {string | number}
+ */
 export function overloaded(a: string, b: boolean): string;
+/**
+ * @overload
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ *
+ * @overload
+ * @param {string} a
+ * @param {boolean} b
+ * @returns {string}
+ */
 export function uncheckedInternally(a: number, b: number): number;
+/**
+ * @overload
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ *
+ * @overload
+ * @param {string} a
+ * @param {boolean} b
+ * @returns {string}
+ */
 export function uncheckedInternally(a: string, b: boolean): string;
diff --git a/tests/baselines/reference/overloadTag2.js b/tests/baselines/reference/overloadTag2.js
@@ -73,8 +73,25 @@ var d = new Foo('str', 2);
 
 //// [overloadTag2.d.ts]
 export class Foo {
+    /**
+         * Should not have an implicit any error, because constructor's return type is always implicit
+         * @constructor
+         * @overload
+         * @param {string} a
+         * @param {number} b
+         */
     constructor(a: string, b: number);
+    /**
+         * @constructor
+         * @overload
+         * @param {number} a
+         */
     constructor(a: number);
+    /**
+         * @constructor
+         * @overload
+         * @param {string} a
+         */
     constructor(a: string);
     #private;
 }
diff --git a/tests/baselines/reference/templateInsideCallback.js b/tests/baselines/reference/templateInsideCallback.js
@@ -114,7 +114,21 @@ function flatMap(array, iterable) {
 
 
 //// [templateInsideCallback.d.ts]
+/**
+ * @overload
+ * @template T
+ * @template U
+ * @param {T[]} array
+ * @param {(x: T) => U[]} iterable
+ * @returns {U[]}
+ */
 declare function flatMap<U>(): any;
+/**
+ * @overload
+ * @template T
+ * @param {T[][]} array
+ * @returns {T[]}
+ */
 declare function flatMap(): any;
 /**
  * @typedef Oops