Skip to content

Commit fa51faf

Browse files
committed
Document the JSDoc @overload tag
The description and example are mostly copied and rephrased from the 5.0 Release Note and /docs/handbook/2/functions.html#function-overloads. It is placed after `@param` and `@returns` because it also concerns functions.
1 parent 9ec526c commit fa51faf

File tree

1 file changed

+43
-0
lines changed

1 file changed

+43
-0
lines changed

packages/documentation/copy/en/javascript/JSDoc Reference.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Note:
1919
- [`@import`](#import)
2020
- [`@param`](#param-and-returns) (or [`@arg`](#param-and-returns) or [`@argument`](#param-and-returns))
2121
- [`@returns`](#param-and-returns) (or [`@return`](#param-and-returns))
22+
- [`@overload`](#overload)
2223
- [`@typedef`](#typedef-callback-and-param)
2324
- [`@callback`](#typedef-callback-and-param)
2425
- [`@template`](#template)
@@ -293,6 +294,48 @@ function ps() {}
293294
function ab() {}
294295
```
295296

297+
### `@overload`
298+
299+
[Overloads](/docs/handbook/2/functions.html#function-overloads) can be declared with the `@overload` tag.
300+
Each JSDoc comment with an `@overload` tag is treated as a distinct overload for the following function declaration.
301+
302+
```js twoslash
303+
// @errors: 2575
304+
// @ts-check
305+
// 3 argument overload
306+
/**
307+
* @overload
308+
* @param {number} m
309+
* @param {number} d
310+
* @param {number} y
311+
* @returns {Date}
312+
*/
313+
// 1 argument overload
314+
/**
315+
* @overload
316+
* @param {number} timestamp
317+
* @returns {Date}
318+
*/
319+
// implementation signature
320+
/**
321+
* @param {number} mOrTimestamp
322+
* @param {number} [d]
323+
* @param {number} [y]
324+
* @returns {Date}
325+
*/
326+
function makeDate(mOrTimestamp, d, y) {
327+
if (d !== undefined && y !== undefined) {
328+
return new Date(y, mOrTimestamp, d);
329+
} else {
330+
return new Date(mOrTimestamp);
331+
}
332+
}
333+
const d1 = makeDate(12345678);
334+
const d2 = makeDate(5, 5, 5);
335+
const d3 = makeDate(1, 3);
336+
337+
```
338+
296339
### `@typedef`, `@callback`, and `@param`
297340

298341
You can define complex types with `@typedef`.

0 commit comments

Comments
 (0)