From fa51faf12482e4d764c08aeddcbf0fe3f48aa6ac Mon Sep 17 00:00:00 2001
From: Kisaragi Hiu <mail@kisaragi-hiu.com>
Date: Tue, 30 Dec 2025 05:13:01 +0900
Subject: [PATCH] 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.
---
 .../copy/en/javascript/JSDoc Reference.md     | 43 +++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/packages/documentation/copy/en/javascript/JSDoc Reference.md b/packages/documentation/copy/en/javascript/JSDoc Reference.md
index 7f84959c1ee9..df25dfb17509 100644
--- a/packages/documentation/copy/en/javascript/JSDoc Reference.md	
+++ b/packages/documentation/copy/en/javascript/JSDoc Reference.md	
@@ -19,6 +19,7 @@ Note:
 - [`@import`](#import)
 - [`@param`](#param-and-returns) (or [`@arg`](#param-and-returns) or [`@argument`](#param-and-returns))
 - [`@returns`](#param-and-returns) (or [`@return`](#param-and-returns))
+- [`@overload`](#overload)
 - [`@typedef`](#typedef-callback-and-param)
 - [`@callback`](#typedef-callback-and-param)
 - [`@template`](#template)
@@ -293,6 +294,48 @@ function ps() {}
 function ab() {}
 ```
 
+### `@overload`
+
+[Overloads](/docs/handbook/2/functions.html#function-overloads) can be declared with the `@overload` tag.
+Each JSDoc comment with an `@overload` tag is treated as a distinct overload for the following function declaration.
+
+```js twoslash
+// @errors: 2575
+// @ts-check
+// 3 argument overload
+/**
+ * @overload
+ * @param {number} m
+ * @param {number} d
+ * @param {number} y
+ * @returns {Date}
+ */
+// 1 argument overload
+/**
+ * @overload
+ * @param {number} timestamp
+ * @returns {Date}
+ */
+// implementation signature
+/**
+ * @param {number} mOrTimestamp
+ * @param {number} [d]
+ * @param {number} [y]
+ * @returns {Date}
+ */
+function makeDate(mOrTimestamp, d, y) {
+  if (d !== undefined && y !== undefined) {
+    return new Date(y, mOrTimestamp, d);
+  } else {
+    return new Date(mOrTimestamp);
+  }
+}
+const d1 = makeDate(12345678);
+const d2 = makeDate(5, 5, 5);
+const d3 = makeDate(1, 3);
+
+```
+
 ### `@typedef`, `@callback`, and `@param`
 
 You can define complex types with `@typedef`.