Update to 1.43.0-wmf.24

Derugon · Oct 5, 2024 · beb6914 · beb6914
1 parent 3796925
commit beb6914
Show file tree

Hide file tree

Showing 28 changed files with 222 additions and 189 deletions.
diff --git a/jquery/confirmable.d.ts b/jquery/confirmable.d.ts
@@ -2,7 +2,6 @@ declare global {
     interface JQuery {
         /**
          * Enable inline confirmation for given clickable element (like `<a />` or `<button />`).
-         * Provided by the `jquery.confirmable` ResourceLoader module.
          *
          * An additional inline confirmation step being shown before the default action is carried out on
          * click.
@@ -15,6 +14,8 @@ declare global {
          * If the computed values for the element are different when you make it confirmable, you might
          * encounter unexpected behavior.
          *
+         * To use this {@link jQuery} plugin, load the `jquery.confirmable` module with {@link mw.loader}.
+         *
          * @example
          * ```js
          * mw.loader.using( 'jquery.confirmable' ).then( () => {

diff --git a/jquery/cookie.d.ts b/jquery/cookie.d.ts
@@ -3,6 +3,8 @@ declare global {
         /**
          * Set a cookie.
          *
+         * To use this {@link jQuery} plugin, load the `mediawiki.cookie` module using {@link mw.loader}.
+         *
          * @example
          * ```js
          * mw.loader.using( 'mediawiki.cookie' ).then( () => {
@@ -25,6 +27,8 @@ declare global {
         /**
          * Remove a cookie by key.
          *
+         * To use this {@link jQuery} plugin, load the `mediawiki.cookie` module using {@link mw.loader}.
+         *
          * @example
          * ```js
          * mw.loader.using( 'mediawiki.cookie' ).then( () => {

diff --git a/jquery/highlightText.d.ts b/jquery/highlightText.d.ts
@@ -6,7 +6,8 @@ declare global {
     interface JQuery {
         /**
          * Highlight certain text in current nodes (by wrapping it in `<span class="highlight">...</span>`).
-         * Provided by the `jquery.highlightText` ResourceLoader module.
+         *
+         * To use this {@link jQuery} plugin, load the `jquery.highlightText` module with {@link mw.loader}.
          *
          * @example
          * ```js

diff --git a/jquery/lengthLimit.d.ts b/jquery/lengthLimit.d.ts
@@ -51,7 +51,7 @@ declare global {
          * For unfortunate historical reasons, browsers' native maxlength counts
          * {@link https://www.w3.org/TR/html5/sec-forms.html#limiting-user-input-length-the-maxlength-attribute the number of UTF-16
          * code units rather than Unicode codepoints}, which means that codepoints outside the Basic
-         * Multilingual Plane (e.g. many emojis) count as 2 characters each. This plugin exists to
+         * Multilingual Plane (such as many emojis) count as 2 characters each. This plugin exists to
          * correct this.
          *
          * Can be called with a custom limit (to use that limit instead of the maxlength attribute

diff --git a/jquery/makeCollapsible.d.ts b/jquery/makeCollapsible.d.ts
@@ -2,14 +2,15 @@ declare global {
     interface JQuery {
         /**
          * Enable collapsible-functionality on all elements in the collection.
-         * Provided by the `jquery.makeCollapsible` ResourceLoader module.
          *
          * - Will prevent binding twice to the same element.
          * - Initial state is expanded by default, this can be overridden by adding class
          *   "mw-collapsed" to the "mw-collapsible" element.
          * - Elements made collapsible have jQuery data "mw-made-collapsible" set to true.
          * - The inner content is wrapped in a "div.mw-collapsible-content" (except for tables and lists).
          *
+         * To use this {@link jQuery} plugin, load the `jquery.makeCollapsible` module with {@link mw.loader}.
+         *
          * @example
          * ```js
          * mw.loader.using( 'jquery.makeCollapsible' ).then( () => {

diff --git a/jquery/spinner.d.ts b/jquery/spinner.d.ts
@@ -5,8 +5,8 @@ declare global {
          *
          * The argument is an object with options used to construct the spinner (see below).
          *
-         * It is a good practice to keep a reference to the created spinner to be able to remove it
-         * later. Alternatively, one can use the 'id' option and {@link removeSpinner} (but make sure to choose
+         * It is a good practice to keep a reference to the created spinner to be able to remove it later.
+         * Alternatively, one can use the 'id' option and {@link removeSpinner} (but make sure to choose
          * an id that's unlikely to cause conflicts, e.g. with extensions, gadgets or user scripts).
          *
          * CSS classes used:
@@ -18,12 +18,12 @@ declare global {
          * @example
          * ```js
          * // Create a large spinner reserving all available horizontal space.
-         * var $spinner = $.createSpinner( { size: 'large', type: 'block' } );
+         * const $spinner = $.createSpinner( { size: 'large', type: 'block' } );
          * // Insert above page content.
          * $( '#mw-content-text' ).prepend( $spinner );
          *
          * // Place a small inline spinner next to the "Save" button
-         * var $spinner = $.createSpinner( { size: 'small', type: 'inline' } );
+         * const $spinner = $.createSpinner( { size: 'small', type: 'inline' } );
          * // Alternatively, just `$.createSpinner();` as these are the default options.
          * $( '#wpSave' ).after( $spinner );
          *
@@ -34,7 +34,7 @@ declare global {
          *
          * @ignore
          * @param {string|Options} [opts] Options. If a string is given, it will be treated as the value
-         *  of the `id` option.
+         *  of the {@link Options.id id} option.
          * @returns {JQuery}
          */
         createSpinner(opts?: string | Options): JQuery;
@@ -58,7 +58,7 @@ declare global {
          * Collection contents remain unchanged.
          *
          * @param {string|Options} [opts] Options. If a string is given, it will be treated as the value
-         *  of the `id` option.
+         *  of the {@link Options.id id} option.
          * @returns {JQuery}
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/jQueryPlugins.html#.injectSpinner
          */

diff --git a/jquery/suggestions.d.ts b/jquery/suggestions.d.ts
@@ -1,8 +1,9 @@
 declare global {
     interface JQuery {
         /**
-         * This plugin provides a generic way to add suggestions to a text box.
-         * Provided by the `jquery.suggestions` ResourceLoader module.
+         * Add suggestions to a text box.
+         *
+         * To use this {@link jQuery} plugin, load the `jquery.suggestions` module with {@link mw.loader}.
          *
          * @example
          * ```js

diff --git a/jquery/tablesorter.d.ts b/jquery/tablesorter.d.ts
@@ -6,7 +6,8 @@ declare global {
     interface JQuery {
         /**
          * Create a sortable table with multi-column sorting capabilities.
-         * Provided by `jquery.tablesorter` ResourceLoader module.
+         *
+         * To use this {@link jQuery} plugin, load the `jquery.tablesorter` module with {@link mw.loader}.
          *
          * ```js
          * // Create a simple tablesorter interface

diff --git a/jquery/updateTooltipAccessKeys.d.ts b/jquery/updateTooltipAccessKeys.d.ts
@@ -11,7 +11,8 @@ type KeyModifier = "alt" | "alt-shift" | "ctrl" | "ctrl-option";
 interface TooltipAccessKeys<This = JQuery> {
     /**
      * Update the titles for all elements in a jQuery selection.
-     * Installed by {@link mediawiki.util} module.
+     *
+     * To use this {@link jQuery} plugin, load the `mediawiki.util` module using {@link mw.loader}.
      *
      * @example
      * ```js

diff --git a/mw/Api.d.ts b/mw/Api.d.ts
@@ -87,15 +87,16 @@ interface FinishUpload {
 declare global {
     namespace mw {
         /**
-         * Interact with the API of a particular MediaWiki site. mw.Api objects represent the API of
-         * one particular MediaWiki site.
+         * Interact with the MediaWiki API. `mw.Api` is a client library for the
+         * {@link https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page action API}.
+         * An `mw.Api` object represents the API of a MediaWiki site. For the REST API, see {@link mw.Rest}.
          *
          * ```js
          * var api = new mw.Api();
          * api.get( {
          *     action: 'query',
          *     meta: 'userinfo'
-         * } ).done( function ( data ) {
+         * } ).then( function ( data ) {
          *     console.log( data );
          * } );
          * ```
@@ -107,7 +108,7 @@ declare global {
          * api.get( {
          *     action: 'query',
          *     meta: [ 'userinfo', 'siteinfo' ] // same effect as 'userinfo|siteinfo'
-         * } ).done( function ( data ) {
+         * } ).then( function ( data ) {
          *     console.log( data );
          * } );
          * ```
@@ -120,6 +121,8 @@ declare global {
          */
         class Api {
             /**
+             * Create an instance of {@link mw.Api}.
+             *
              * @param {Api.Options} [options] See {@link mw.Api.Options}. This can also be overridden for
              *  each request by passing them to {@link get()} or {@link post()} (or directly to {@link ajax()}) later on.
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.Api.html#Api
@@ -620,12 +623,18 @@ declare global {
              * Asynchronously save the value of a single user option using the API.
              * See {@link saveOptions()}.
              *
+             * @since 1.28 - params parameter can be passed.
              * @param {string} name
              * @param {string|null} value
+             * @param {UnknownApiParams} [params] additional parameters for API.
              * @returns {JQuery.Promise<ApiResponse>}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.Api.html#saveOption
              */
-            saveOption(name: string, value: string | null): JQuery.Promise<ApiResponse>;
+            saveOption(
+                name: string,
+                value: string | null,
+                params?: UnknownApiParams
+            ): JQuery.Promise<ApiResponse>;
 
             /**
              * Asynchronously save the values of user options using the {@link https://www.mediawiki.org/wiki/Special:MyLanguage/API:Options Options API}.
@@ -642,11 +651,16 @@ declare global {
              * completed, otherwise MediaWiki gets sad. No requests are sent for anonymous users, as they
              * would fail anyway. See T214963.
              *
+             * @since 1.28 - params parameter can be passed.
              * @param {Object.<string, string|null>} options Options as a `{ name: value, … }` object
+             * @param {UnknownApiParams} [params] additional parameters for API.
              * @returns {JQuery.Promise<ApiResponse>}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.Api.html#saveOptions
              */
-            saveOptions(options: Record<string, string | null>): JQuery.Promise<ApiResponse>;
+            saveOptions(
+                options: Record<string, string | null>,
+                params?: UnknownApiParams
+            ): JQuery.Promise<ApiResponse>;
 
             /**
              * Convenience method for `action=watch&unwatch=1`.

diff --git a/mw/ForeignApi.d.ts b/mw/ForeignApi.d.ts
@@ -1,6 +1,37 @@
 declare global {
     namespace mw {
         /**
+         * Interact with the API of another MediaWiki site. mw.Foreign API creates
+         * an object like {@link mw.Api}, but automatically handle everything required to communicate
+         *
+         * The foreign wiki must be configured to accept requests from the current wiki. See
+         * {@link https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:$wgCrossSiteAJAXdomains} for details.
+         *
+         * ```js
+         * const api = new mw.ForeignApi( 'https://commons.wikimedia.org/w/api.php' );
+         * api.get( {
+         *     action: 'query',
+         *     meta: 'userinfo'
+         * } ).done( function ( data ) {
+         *     console.log( data );
+         * } );
+         * ```
+         *
+         * To ensure that the user at the foreign wiki is logged in, pass the `assert: 'user'` parameter
+         * to {@link ForeignApi.get get()}/{@link ForeignApi.post post()} (since MW 1.23), otherwise
+         * the API request will fail. (Note that this doesn't guarantee that it's the same user. To assert
+         * that the user at the foreign wiki has a specific username, pass the `assertuser` parameter with
+         * the desired username.)
+         *
+         * Authentication-related MediaWiki extensions may extend this class to ensure that the user authenticated on the current wiki will be automatically authenticated on the foreign one. These extension modules should be registered using the ResourceLoaderForeignApiModules hook. See CentralAuth for a practical example. The general pattern to extend and override the name is:
+         *
+         * ```js
+         * function MyForeignApi() {};
+         * OO.inheritClass( MyForeignApi, mw.ForeignApi );
+         * mw.ForeignApi = MyForeignApi;
+         * ```
+         *
+         * @since 1.26
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.ForeignApi.html
          */
         class ForeignApi extends Api {
@@ -10,37 +41,8 @@ declare global {
             static parent: typeof Api;
 
             /**
-             * Create an object like {@link mw.Api}, but automatically handling everything required to communicate
-             * with another MediaWiki wiki via cross-origin requests (CORS).
+             * Create an instance of {@link mw.ForeignApi}.
              *
-             * The foreign wiki must be configured to accept requests from the current wiki. See
-             * {@link https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:$wgCrossSiteAJAXdomains} for details.
-             *
-             * ```js
-             * var api = new mw.ForeignApi( 'https://commons.wikimedia.org/w/api.php' );
-             * api.get( {
-             *     action: 'query',
-             *     meta: 'userinfo'
-             * } ).done( function ( data ) {
-             *     console.log( data );
-             * } );
-             * ```
-             *
-             * To ensure that the user at the foreign wiki is logged in, pass the `assert: 'user'` parameter
-             * to {@link mw.ForeignApi.get}/{@link mw.ForeignApi.post} (since MW 1.23), otherwise the API
-             * request will fail. (Note that this doesn't guarantee that it's the same user. To assert that
-             * the user at the foreign wiki has a specific username, pass the `assertuser` parameter with
-             * the desired username.)
-             *
-             * Authentication-related MediaWiki extensions may extend this class to ensure that the user authenticated on the current wiki will be automatically authenticated on the foreign one. These extension modules should be registered using the ResourceLoaderForeignApiModules hook. See CentralAuth for a practical example. The general pattern to extend and override the name is:
-             *
-             * ```js
-             * function MyForeignApi() {};
-             * OO.inheritClass( MyForeignApi, mw.ForeignApi );
-             * mw.ForeignApi = MyForeignApi;
-             * ```
-             *
-             * @since 1.26
              * @param {string|Uri} url URL pointing to another wiki's `api.php` endpoint.
              * @param {ForeignApi.Options} [options] Also accepts all the options from {@link mw.Api.Options}.
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.ForeignApi.html#ForeignApi

diff --git a/mw/ForeignRest.d.ts b/mw/ForeignRest.d.ts
@@ -1,6 +1,33 @@
 declare global {
     namespace mw {
         /**
+         * Interact with the REST API of another MediaWiki site. mw.ForeignRest creates
+         * an object like {@link mw.Rest}, but automatically handles everything required to communicate
+         * with another MediaWiki wiki via cross-origin requests (CORS).
+         *
+         * The foreign wiki must be configured to accept requests from the current wiki. See
+         * {@link https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:$wgCrossSiteAJAXdomains} for details.
+         *
+         * ```js
+         * const api = new mw.ForeignRest( 'https://commons.wikimedia.org/w/rest.php' );
+         * api.get( '/page/Main_Page/html' )
+         * .done( function ( data ) {
+         *     console.log( data );
+         * } );
+         * ```
+         *
+         * Authentication-related MediaWiki extensions may extend this class to ensure that the user
+         * authenticated on the current wiki will be automatically authenticated on the foreign one. These
+         * extension modules should be registered using the ResourceLoaderForeignApiModules hook. See
+         * CentralAuth for a practical example. The general pattern to extend and override the name is:
+         *
+         * ```js
+         * function MyForeignRest() {};
+         * OO.inheritClass( MyForeignRest, mw.ForeignRest );
+         * mw.ForeignRest = MyForeignRest;
+         * ```
+         *
+         * @since 1.36
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.ForeignRest.html
          */
         class ForeignRest extends Rest {
@@ -10,32 +37,8 @@ declare global {
             static parent: typeof Rest;
 
             /**
-             * Create an object like {@link mw.Rest}, but automatically handling everything required to communicate
-             * with another MediaWiki wiki via cross-origin requests (CORS).
+             * Create an instance of {@link mw.ForeignRest}.
              *
-             * The foreign wiki must be configured to accept requests from the current wiki. See
-             * {@link https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:$wgCrossSiteAJAXdomains} for details.
-             *
-             * ```js
-             * var api = new mw.ForeignRest( 'https://commons.wikimedia.org/w/rest.php' );
-             * api.get( '/page/Main_Page/html' )
-             * .done( function ( data ) {
-             *     console.log( data );
-             * } );
-             * ```
-             *
-             * Authentication-related MediaWiki extensions may extend this class to ensure that the user
-             * authenticated on the current wiki will be automatically authenticated on the foreign one. These
-             * extension modules should be registered using the ResourceLoaderForeignApiModules hook. See
-             * CentralAuth for a practical example. The general pattern to extend and override the name is:
-             *
-             * ```js
-             * function MyForeignRest() {};
-             * OO.inheritClass( MyForeignRest, mw.ForeignRest );
-             * mw.ForeignRest = MyForeignRest;
-             * ```
-             *
-             * @since 1.36
              * @param {string} url URL pointing to another wiki's `rest.php` endpoint.
              * @param {ForeignApi} foreignActionApi
              * @param {ForeignRest.Options} [options] See {@link mw.Rest}.

diff --git a/mw/ForeignUpload.d.ts b/mw/ForeignUpload.d.ts
@@ -1,7 +1,7 @@
 declare global {
     namespace mw {
         /**
-         * Used to represent an upload in progress on the frontend.
+         * Upload to another MediaWiki site.
          *
          * Subclassed to upload to a foreign API, with no other goodies. Use
          * this for a generic foreign image repository on your wiki farm.
@@ -38,13 +38,6 @@ declare global {
             /**
              * Used to represent an upload in progress on the frontend.
              *
-             * Subclassed to upload to a foreign API, with no other goodies. Use
-             * this for a generic foreign image repository on your wiki farm.
-             *
-             * Note you can provide the {@link target} or not - if the first argument is
-             * an object, we assume you want the default, and treat it as apiconfig
-             * instead.
-             *
              * @param {string} [target] Used to set up the target
              *     wiki. If not remote, this class behaves identically to mw.Upload (unless further subclassed)
              *     Use the same names as set in $wgForeignFileRepos for this. Also,