diff --git a/mw/Api.d.ts b/mw/Api.d.ts index 726d65d..00547e3 100644 --- a/mw/Api.d.ts +++ b/mw/Api.d.ts @@ -14,7 +14,7 @@ import { TitleLike } from "./Title"; type TypeOrArray = T extends any ? T | T[] : never; // T[] would be a mixed array type ReplaceValue = T extends U[] ? V[] : V; -type UnknownApiParams = Record; +type UnknownApiParams = Record; export type ApiResponse = Record; // 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>} @@ -445,7 +446,7 @@ declare global { type: ApiTokenType, additionalParams?: ApiQueryTokensParams | ApiAssert ): JQuery.Promise; - /** @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} @@ -589,7 +591,7 @@ declare global { params: UnknownApiParams, ajaxOptions?: JQuery.AjaxSettings ): JQuery.Promise; - /** @deprecated Use "csrf" instead */ + /** @deprecated Use `postWithToken('csrf', params)` instead */ postWithToken( tokenType: ApiLegacyTokenType, params: UnknownApiParams, diff --git a/mw/ForeignRest.d.ts b/mw/ForeignRest.d.ts index b4d813f..2c6ef41 100644 --- a/mw/ForeignRest.d.ts +++ b/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 { diff --git a/mw/Rest.d.ts b/mw/Rest.d.ts index a886aa3..8b05063 100644 --- a/mw/Rest.d.ts +++ b/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.} body * @param {Object.} [headers] @@ -110,6 +111,7 @@ declare global { * * Note: only sending `application/json` is currently supported. * + * @since 1.39 * @param {string} path * @param {Object.} body * @param {Object.} [headers] diff --git a/mw/errorLogger.d.ts b/mw/errorLogger.d.ts index 235c0b9..d63d3f1 100644 --- a/mw/errorLogger.d.ts +++ b/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 diff --git a/mw/language.d.ts b/mw/language.d.ts index 022da3d..e6d9cc1 100644 --- a/mw/language.d.ts +++ b/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. diff --git a/mw/loader.d.ts b/mw/loader.d.ts index 1c43080..404b873 100644 --- a/mw/loader.d.ts +++ b/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 diff --git a/mw/message.d.ts b/mw/message.d.ts index 383e974..f774390 100644 --- a/mw/message.d.ts +++ b/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 diff --git a/mw/notification.d.ts b/mw/notification.d.ts index de8be0c..968af1a 100644 --- a/mw/notification.d.ts +++ b/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; diff --git a/mw/storage.d.ts b/mw/storage.d.ts index 5be050c..fa69e29 100644 --- a/mw/storage.d.ts +++ b/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; @@ -85,6 +89,7 @@ interface SafeStorage { * Get all keys with expiry values. * * @private + * @since 1.39 * @returns {JQuery.Promise} 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 */ diff --git a/mw/util.d.ts b/mw/util.d.ts index c2a7c0f..1fd142d 100644 --- a/mw/util.d.ts +++ b/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; + + /** + * 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 any>( - wait: number, - func: T + delay: number, + callback: T ): NoReturn; /** @@ -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 diff --git a/vue/index.d.ts b/vue/index.d.ts index e66feb1..c5942a5 100644 --- a/vue/index.d.ts +++ b/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