Annotate changes from previous LTS

- add `@since` annotations for declarations added/modified with versions between the previous LTS (1.35) and the current one (1.39)
- add deprecation warning to the old `mw.util.debounce` signature (replaced and deprecated since 1.38)

and fix the previous commit reverting the one before it

mw/Api.d.ts

@@ -14,7 +14,7 @@ import { TitleLike } from "./Title";
 type TypeOrArray<T> = T extends any ? T | T[] : never; // T[] would be a mixed array
 type ReplaceValue<T extends U | U[], U, V> = T extends U[] ? V[] : V;
 
-type UnknownApiParams = Record<string, string | string[] | boolean | number | number[]>;
+type UnknownApiParams = Record<string, string | number | boolean | string[] | number[] | undefined>;
 
 export type ApiResponse = Record<string, any>; // it will always be a JSON object, the rest is uncertain ...
 
@@ -211,7 +211,7 @@ declare global {
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.Api.html#badToken
              */
             badToken(type: ApiTokenType): void;
-            /** @deprecated Use "csrf" instead */
+            /** @deprecated Use `badToken('csrf')` instead */
             badToken(type: ApiLegacyTokenType): void;
             badToken(type: string): void;
 
@@ -420,6 +420,7 @@ declare global {
              * Get a set of messages.
              *
              * @since 1.27
+             * @since 1.37 - accepts a single string message as parameter.
              * @param {string|string[]} messages Messages to retrieve
              * @param {ApiQueryAllMessagesParams} [options] Additional parameters for the API call
              * @returns {JQuery.Promise<Object.<string, string>>}
@@ -445,7 +446,7 @@ declare global {
                 type: ApiTokenType,
                 additionalParams?: ApiQueryTokensParams | ApiAssert
             ): JQuery.Promise<string>;
-            /** @deprecated Use "csrf" instead */
+            /** @deprecated Use `getToken('csrf')` instead */
             getToken(
                 type: ApiLegacyTokenType,
                 additionalParams?: ApiQueryTokensParams | ApiAssert
@@ -476,6 +477,7 @@ declare global {
             /**
              * Load a set of messages and add them to {@link mw.messages}.
              *
+             * @since 1.37 - accepts a single string message as parameter.
              * @param {string|string[]} messages Messages to retrieve
              * @param {ApiQueryAllMessagesParams} [options] Additional parameters for the API call
              * @returns {JQuery.Promise<boolean>}
@@ -589,7 +591,7 @@ declare global {
                 params: UnknownApiParams,
                 ajaxOptions?: JQuery.AjaxSettings
             ): JQuery.Promise<ApiResponse>;
-            /** @deprecated Use "csrf" instead */
+            /** @deprecated Use `postWithToken('csrf', params)` instead */
             postWithToken(
                 tokenType: ApiLegacyTokenType,
                 params: UnknownApiParams,

mw/ForeignRest.d.ts

@@ -1,6 +1,7 @@
 declare global {
     namespace mw {
         /**
+         * @since 1.36
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.ForeignRest.html
          */
         class ForeignRest extends Rest {

mw/Rest.d.ts

@@ -60,6 +60,7 @@ declare global {
              *
              * Note: only sending `application/json` is currently supported.
              *
+             * @since 1.39
              * @param {string} path
              * @param {Object.<string, any>} body
              * @param {Object.<string, any>} [headers]
@@ -110,6 +111,7 @@ declare global {
              *
              * Note: only sending `application/json` is currently supported.
              *
+             * @since 1.39
              * @param {string} path
              * @param {Object.<string, any>} body
              * @param {Object.<string, any>} [headers]

mw/errorLogger.d.ts

@@ -10,6 +10,7 @@ declare global {
              * Logs an error by notifying subscribers to the given {@link mw.track()} topic
              * (by default `error.caught`) that an event has occurred.
              *
+             * @since 1.36
              * @param {Error} error
              * @param {string} [topic='error.caught'] Error topic. Conventionally in the form
              *  'error.%component%' (where %component% identifies the code logging the error at a

mw/language.d.ts

@@ -64,7 +64,7 @@ declare global {
              * Using patterns from {@link https://www.unicode.org/reports/tr35/#Number_Format_Patterns Unicode TR35}.
              *
              * @private
-             * @deprecated This function will be made private in a future release;
+             * @deprecated since 1.36 - This function will be made private in a future release;
              *  it is poorly named, corresponds to a deprecated function in core, and
              *  its functionality should be rolled into convertNumber().
              * @deprecated Removed since 1.40.

mw/loader.d.ts

@@ -263,6 +263,7 @@ declare global {
              * Utility function for execute()
              *
              * @private
+             * @since 1.39
              * @param {string} url URL
              * @param {string} [media] Media attribute
              * @param {Node|null} [nextNode]
@@ -278,6 +279,7 @@ declare global {
              * Load and execute a script.
              *
              * @private
+             * @since 1.39
              * @param {string} src URL to script, will be used as the src attribute in the script tag
              * @param {function():void} [callback] Callback to run after request resolution
              * @param {string[]} [modules] List of modules being requested, for state to be marked as error

mw/message.d.ts

@@ -201,6 +201,7 @@ declare global {
              * This function will not be called for nonexistent messages.
              *
              * @private For internal use by mediawiki.jqueryMsg only
+             * @since 1.38 - format parameter can be passed.
              * @param {string} format
              * @returns {string} Parsed message
              */
@@ -213,6 +214,7 @@ declare global {
              * Do not call this directly. Use {@link mw.Message.text()} instead, one of the
              * other format methods.
              *
+             * @since 1.38 - format parameter can be passed.
              * @param {string} [format="text"] Internal parameter. Uses "text" if called
              *  implicitly through string casting.
              * @returns {string} Message in the given format, or `⧼key⧽` if the key

mw/notification.d.ts

@@ -151,6 +151,8 @@ declare global {
 
                 /**
                  * CSS class names to be set on the notification element.
+                 *
+                 * @since 1.38
                  */
                 classes?: string | string[] | false;
 

mw/storage.d.ts

@@ -40,6 +40,7 @@ interface SafeStorage {
     /**
      * Set a value in device storage.
      *
+     * @since 1.39 - expiry parameter can be passed.
      * @param {string} key Key name to store under
      * @param {string} value Value to be stored
      * @param {number} [expiry] Number of seconds after which this item can be deleted
@@ -51,6 +52,7 @@ interface SafeStorage {
     /**
      * Set the expiry time for an item in the store.
      *
+     * @since 1.39
      * @since 1.41 - returns a boolean indicating whether the expiry was set.
      * @param {string} key Key name
      * @param {number} [expiry] Number of seconds after which this item can be deleted,
@@ -64,6 +66,7 @@ interface SafeStorage {
     /**
      * Set an object value in device storage by JSON encoding.
      *
+     * @since 1.39 - expiry parameter can be passed.
      * @since 1.41 - returns a boolean indicating whether the value was set.
      * @param {string} key Key name to store under
      * @param {Object} value Object value to be stored
@@ -77,6 +80,7 @@ interface SafeStorage {
      * Clear any expired items from the store.
      *
      * @private
+     * @since 1.39
      * @returns {JQuery.Promise} Resolves when items have been expired
      */
     clearExpired(): JQuery.Promise<undefined>;
@@ -85,6 +89,7 @@ interface SafeStorage {
      * Get all keys with expiry values.
      *
      * @private
+     * @since 1.39
      * @returns {JQuery.Promise<string[]>} Promise resolving with all the keys which have
      *  expiry values (unprefixed), or as many could be retrieved in the allocated time.
      */
@@ -94,6 +99,7 @@ interface SafeStorage {
      * Check if a given key has expired.
      *
      * @private
+     * @since 1.39
      * @param {string} key Key name
      * @returns {boolean} Whether key is expired
      */

mw/util.d.ts

@@ -218,6 +218,7 @@ declare global {
              * {@link https://github.com/jashkenas/underscore/blob/1.5.2/underscore.js#L689}.
              *
              * @since 1.34
+             * @since 1.38 - swapped parameter order; immediate parameter can be passed.
              * @param {Function} func Function to debounce
              * @param {number} [wait=0] Wait period in milliseconds
              * @param {boolean} [immediate] Trigger on leading edge
@@ -229,9 +230,26 @@ declare global {
                 wait?: number,
                 immediate?: boolean
             ): NoReturn<T>;
+
+            /**
+             * Return a function, that, as long as it continues to be invoked, will not
+             * be triggered. The function will be called after it stops being called for
+             * N milliseconds.
+             *
+             * Ported from Underscore.js 1.5.2, Copyright 2009-2013 Jeremy Ashkenas, DocumentCloud
+             * and Investigative Reporters & Editors, distributed under the MIT license, from
+             * {@link https://github.com/jashkenas/underscore/blob/1.5.2/underscore.js#L689}.
+             *
+             * @since 1.34
+             * @deprecated since 1.38 - use `mw.util.debounce(func, wait)` instead of `mw.util.debounce(wait, func)`.
+             * @param {number} delay Wait period in milliseconds
+             * @param {Function} callback Function to debounce
+             * @returns {Function} Debounced function
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/module-mediawiki.util.html#.debounce
+             */
             function debounce<T extends (...args: any[]) => any>(
-                wait: number,
-                func: T
+                delay: number,
+                callback: T
             ): NoReturn<T>;
 
             /**
@@ -325,6 +343,7 @@ declare global {
              * is fully encoded, and throws an error on a string like '%A',
              * so we use the percent-decode.
              *
+             * @since 1.39
              * @param {string} [hash] Hash fragment, without the leading '#'.
              *  Taken from location.hash if omitted.
              * @returns {HTMLElement|null} Element, if found
@@ -348,6 +367,7 @@ declare global {
             /**
              * Hide a portlet.
              *
+             * @since 1.36
              * @param {string} portletId ID of the target portlet (e.g. 'p-cactions' or 'p-personal')
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/module-mediawiki.util.html#.hidePortlet
              */
@@ -430,6 +450,7 @@ declare global {
             /**
              * Whether a portlet is visible.
              *
+             * @since 1.36
              * @param {string} portletId ID of the target portlet (e.g. 'p-cactions' or 'p-personal')
              * @returns {boolean}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/module-mediawiki.util.html#.isPortletVisible
@@ -472,6 +493,7 @@ declare global {
              * To get the desired behaviour we percent-encode any '+' in the fragment
              * to effectively expose the percent-decode implementation.
              *
+             * @since 1.39
              * @param {string} text Text to decode
              * @returns {string|null} Decoded text, null if decoding failed
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/module-mediawiki.util.html#.percentDecodeFragment
@@ -485,6 +507,7 @@ declare global {
              *
              * This functionality has been adapted from `\Wikimedia\IPUtils::prettifyIP()`
              *
+             * @since 1.38
              * @param {string} ip IP address in quad or octet form (CIDR or not).
              * @returns {string|null}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/module-mediawiki.util.html#.prettifyIP
@@ -509,6 +532,7 @@ declare global {
              *
              * This functionality has been adapted from `\Wikimedia\IPUtils::sanitizeIP()`
              *
+             * @since 1.38
              * @param {string} ip IP address in quad or octet form (CIDR or not).
              * @returns {string|null}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/module-mediawiki.util.html#.sanitizeIP
@@ -518,6 +542,7 @@ declare global {
             /**
              * Reveal a portlet if it is hidden.
              *
+             * @since 1.36
              * @param {string} portletId ID of the target portlet (e.g. 'p-cactions' or 'p-personal')
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/module-mediawiki.util.html#.showPortlet
              */
@@ -534,6 +559,7 @@ declare global {
              *
              * Ported from OOUI.
              *
+             * @since 1.38
              * @param {Function} func Function to throttle
              * @param {number} wait Throttle window length, in milliseconds
              * @returns {Function} Throttled function

vue/index.d.ts

@@ -11,6 +11,7 @@ declare module "vue" {
      * To ensure all Vue code has the i18n plugin and the error handler installed, use of
      * `vue.createMwApp()` is recommended anywhere one would normally use `Vue.createApp()`.
      *
+     * @since 1.38
      * @method createMwApp
      * @param {...any} args
      * @returns {Object} Vue app instance