Skip to content

JSDoc overload tag #51234

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sandersn merged 8 commits into from
Dec 13, 2022
Merged

JSDoc overload tag #51234

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
7f31b7a
Add support for JSDocOverloadTag
apendua Sep 15, 2022
a6cb519
Use overload tag to determine function type
apendua Oct 16, 2022
dd65e9a
Update baselines
apendua Dec 3, 2022
f659657
Add new tests along with baselines
apendua Sep 15, 2022
7db2335
Add tests for all @overload tags in one comment
apendua Dec 3, 2022
52a94ca
Add tests for find-all-ref and rename operations
apendua Dec 3, 2022
f0ec97c
Add tests for alternative uses of @overload tag
apendua Dec 3, 2022
bf10df0
Merge branch 'main' into pr/apendua/51234
sandersn Dec 13, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Add new tests along with baselines
  • Loading branch information
@apendua
apendua committed Dec 3, 2022
commit f659657b4e23e6a09b5294571c83777e484b9bfd
131 changes: 131 additions & 0 deletions tests/baselines/reference/jsFileFunctionOverloads.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
//// [jsFileFunctionOverloads.js]
/**
* @overload
* @param {number} x
* @returns {'number'}
*/
/**
* @overload
* @param {string} x
* @returns {'string'}
*/
/**
* @overload
* @param {boolean} x
* @returns {'boolean'}
*/
/**
* @param {unknown} x
* @returns {string}
*/
function getTypeName(x) {
return typeof x;
}

/**
* @template T
* @param {T} x
* @returns {T}
*/
const identity = x => x;

/**
* @template T
* @template U
* @overload
* @param {T[]} array
* @param {(x: T) => U[]} iterable
* @returns {U[]}
*/
/**
* @template T
* @overload
* @param {T[][]} array
* @returns {T[]}
*/
/**
* @param {unknown[]} array
* @param {(x: unknown) => unknown} iterable
* @returns {unknown[]}
*/
function flatMap(array, iterable = identity) {
/** @type {unknown[]} */
const result = [];
for (let i = 0; i < array.length; i += 1) {
result.push(.../** @type {unknown[]} */(iterable(array[i])));
}
return result;
}


//// [jsFileFunctionOverloads.js]
/**
* @overload
* @param {number} x
* @returns {'number'}
*/
/**
* @overload
* @param {string} x
* @returns {'string'}
*/
/**
* @overload
* @param {boolean} x
* @returns {'boolean'}
*/
/**
* @param {unknown} x
* @returns {string}
*/
function getTypeName(x) {
return typeof x;
}
/**
* @template T
* @param {T} x
* @returns {T}
*/
var identity = function (x) { return x; };
/**
* @template T
* @template U
* @overload
* @param {T[]} array
* @param {(x: T) => U[]} iterable
* @returns {U[]}
*/
/**
* @template T
* @overload
* @param {T[][]} array
* @returns {T[]}
*/
/**
* @param {unknown[]} array
* @param {(x: unknown) => unknown} iterable
* @returns {unknown[]}
*/
function flatMap(array, iterable) {
if (iterable === void 0) { iterable = identity; }
/** @type {unknown[]} */
var result = [];
for (var i = 0; i < array.length; i += 1) {
result.push.apply(result, /** @type {unknown[]} */ (iterable(array[i])));
}
return result;
}


//// [jsFileFunctionOverloads.d.ts]
declare function getTypeName(x: number): 'number';
declare function getTypeName(x: string): 'string';
declare function getTypeName(x: boolean): 'boolean';
declare function flatMap<T, U>(array: T[], iterable: (x: T) => U[]): U[];
declare function flatMap<T>(array: T[][]): T[];
/**
* @template T
* @param {T} x
* @returns {T}
*/
declare function identity<T>(x: T): T;
87 changes: 87 additions & 0 deletions tests/baselines/reference/jsFileFunctionOverloads.symbols
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
=== tests/cases/compiler/jsFileFunctionOverloads.js ===
/**
* @overload
* @param {number} x
Copy link
Copy Markdown
Member

@sandersn sandersn Nov 15, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what happens if you find-all-ref or rename the overload parameters. In Typescript, they are not connected to the implementation signatures and don't rename.

Can you add two tests in cases/fourslash, one that renames an overload param and one that find-all-refs it, and shows that overload params are not connected to the implementation? There should be existing tests for @param that you can start from.

Copy link
Copy Markdown
Contributor Author

@apendua apendua Nov 16, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I only tried this in VSCode, and it seems like your assumptions are correct, i.e. the overload parameters are generally ignored on both find-all-ref and rename operations.

I would be happy to add those tests, but can you please point me to an example where a similar test was already implemented? I am fairly new to this codebase and navigating around (especially within tests) is still challenging 😄

Copy link
Copy Markdown
Contributor Author

@apendua apendua Dec 3, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added tests for find-all-ref and rename as requested.

* @returns {'number'}
*/
/**
Comment on lines +6 to +7
Copy link
Copy Markdown
Member

@sandersn sandersn Nov 15, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what happens if all the @overload tags are in one comment? Does that work too?

Copy link
Copy Markdown
Contributor Author

@apendua apendua Nov 16, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, actually it does. At least the examples I checked locally seem to work properly. Do you think we should be adding this as a test case?

Copy link
Copy Markdown
Contributor Author

@apendua apendua Dec 3, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just in case, I've also added another variant of tests, which tries to put all @overload tags in a single comment. It seems like things get tricky (unsurprisingly) if you also want to use @template tag, as you can only have a single "scope" for template parameters per JSDoc comment. This problem is not specific to @overload tag though, and I think it should be good enough for now if it's covered in documentation properly. Perhaps this could be improved in the future if we allow @template to be parsed as part of JSDocSignature?

Copy link
Copy Markdown
Member

@sandersn sandersn Dec 13, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I think it's good enough for now.

* @overload
* @param {string} x
* @returns {'string'}
*/
/**
* @overload
* @param {boolean} x
* @returns {'boolean'}
*/
/**
* @param {unknown} x
* @returns {string}
*/
function getTypeName(x) {
>getTypeName : Symbol(getTypeName, Decl(jsFileFunctionOverloads.js, 0, 0))
>x : Symbol(x, Decl(jsFileFunctionOverloads.js, 19, 22))

return typeof x;
>x : Symbol(x, Decl(jsFileFunctionOverloads.js, 19, 22))
}

/**
* @template T
* @param {T} x
* @returns {T}
*/
const identity = x => x;
>identity : Symbol(identity, Decl(jsFileFunctionOverloads.js, 28, 5))
>x : Symbol(x, Decl(jsFileFunctionOverloads.js, 28, 16))
>x : Symbol(x, Decl(jsFileFunctionOverloads.js, 28, 16))

/**
* @template T
* @template U
* @overload
* @param {T[]} array
* @param {(x: T) => U[]} iterable
* @returns {U[]}
*/
/**
* @template T
* @overload
* @param {T[][]} array
* @returns {T[]}
*/
/**
* @param {unknown[]} array
* @param {(x: unknown) => unknown} iterable
* @returns {unknown[]}
*/
function flatMap(array, iterable = identity) {
>flatMap : Symbol(flatMap, Decl(jsFileFunctionOverloads.js, 28, 24))
>array : Symbol(array, Decl(jsFileFunctionOverloads.js, 49, 17))
>iterable : Symbol(iterable, Decl(jsFileFunctionOverloads.js, 49, 23))
>identity : Symbol(identity, Decl(jsFileFunctionOverloads.js, 28, 5))

/** @type {unknown[]} */
const result = [];
>result : Symbol(result, Decl(jsFileFunctionOverloads.js, 51, 7))

for (let i = 0; i < array.length; i += 1) {
>i : Symbol(i, Decl(jsFileFunctionOverloads.js, 52, 10))
>i : Symbol(i, Decl(jsFileFunctionOverloads.js, 52, 10))
>array.length : Symbol(Array.length, Decl(lib.es5.d.ts, --, --))
>array : Symbol(array, Decl(jsFileFunctionOverloads.js, 49, 17))
>length : Symbol(Array.length, Decl(lib.es5.d.ts, --, --))
>i : Symbol(i, Decl(jsFileFunctionOverloads.js, 52, 10))

result.push(.../** @type {unknown[]} */(iterable(array[i])));
>result.push : Symbol(Array.push, Decl(lib.es5.d.ts, --, --))
>result : Symbol(result, Decl(jsFileFunctionOverloads.js, 51, 7))
>push : Symbol(Array.push, Decl(lib.es5.d.ts, --, --))
>iterable : Symbol(iterable, Decl(jsFileFunctionOverloads.js, 49, 23))
>array : Symbol(array, Decl(jsFileFunctionOverloads.js, 49, 17))
>i : Symbol(i, Decl(jsFileFunctionOverloads.js, 52, 10))
}
return result;
>result : Symbol(result, Decl(jsFileFunctionOverloads.js, 51, 7))
}

99 changes: 99 additions & 0 deletions tests/baselines/reference/jsFileFunctionOverloads.types
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
=== tests/cases/compiler/jsFileFunctionOverloads.js ===
/**
* @overload
* @param {number} x
* @returns {'number'}
*/
/**
* @overload
* @param {string} x
* @returns {'string'}
*/
/**
* @overload
* @param {boolean} x
* @returns {'boolean'}
*/
/**
* @param {unknown} x
* @returns {string}
*/
function getTypeName(x) {
>getTypeName : { (x: number): 'number'; (x: string): 'string'; (x: boolean): 'boolean'; }
>x : unknown

return typeof x;
>typeof x : "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function"
>x : unknown
}

/**
* @template T
* @param {T} x
* @returns {T}
*/
const identity = x => x;
>identity : <T>(x: T) => T
>x => x : <T>(x: T) => T
>x : T
>x : T

/**
* @template T
* @template U
* @overload
Comment thread
sandersn marked this conversation as resolved.
* @param {T[]} array
* @param {(x: T) => U[]} iterable
* @returns {U[]}
*/
/**
* @template T
* @overload
* @param {T[][]} array
* @returns {T[]}
*/
/**
* @param {unknown[]} array
* @param {(x: unknown) => unknown} iterable
* @returns {unknown[]}
*/
function flatMap(array, iterable = identity) {
>flatMap : { <T, U>(array: T[], iterable: (x: T) => U[]): U[]; <T>(array: T[][]): T[]; }
>array : unknown[]
>iterable : (x: unknown) => unknown
>identity : <T>(x: T) => T

/** @type {unknown[]} */
const result = [];
>result : unknown[]
>[] : undefined[]

for (let i = 0; i < array.length; i += 1) {
>i : number
>0 : 0
>i < array.length : boolean
>i : number
>array.length : number
>array : unknown[]
>length : number
>i += 1 : number
>i : number
>1 : 1

result.push(.../** @type {unknown[]} */(iterable(array[i])));
>result.push(.../** @type {unknown[]} */(iterable(array[i]))) : number
>result.push : (...items: unknown[]) => number
>result : unknown[]
>push : (...items: unknown[]) => number
>.../** @type {unknown[]} */(iterable(array[i])) : unknown
>(iterable(array[i])) : unknown[]
>iterable(array[i]) : unknown
>iterable : (x: unknown) => unknown
>array[i] : unknown
>array : unknown[]
>i : number
}
return result;
>result : unknown[]
}

Loading