From beb69146dfe41338b2efd928a6e7862679bb7921 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adrien=20LES=C3=89N=C3=89CHAL?=
 <adrien.lesenechal@etu.univ-nantes.fr>
Date: Sat, 5 Oct 2024 16:17:11 +0200
Subject: [PATCH] Update to 1.43.0-wmf.24

---
 jquery/confirmable.d.ts             |  3 +-
 jquery/cookie.d.ts                  |  4 ++
 jquery/highlightText.d.ts           |  3 +-
 jquery/lengthLimit.d.ts             |  2 +-
 jquery/makeCollapsible.d.ts         |  3 +-
 jquery/spinner.d.ts                 | 12 +++---
 jquery/suggestions.d.ts             |  5 ++-
 jquery/tablesorter.d.ts             |  3 +-
 jquery/updateTooltipAccessKeys.d.ts |  3 +-
 mw/Api.d.ts                         | 26 +++++++++---
 mw/ForeignApi.d.ts                  | 62 +++++++++++++++--------------
 mw/ForeignRest.d.ts                 | 53 ++++++++++++------------
 mw/ForeignUpload.d.ts               |  9 +----
 mw/Map.d.ts                         | 31 +++++++++++----
 mw/Rest.d.ts                        | 48 +++++++++++-----------
 mw/Title.d.ts                       |  4 +-
 mw/Upload.d.ts                      | 48 ++--------------------
 mw/Uri.d.ts                         |  9 +++--
 mw/cookie.d.ts                      |  6 +--
 mw/debug.d.ts                       |  4 +-
 mw/hook.d.ts                        |  5 ++-
 mw/index.d.ts                       |  3 ++
 mw/language.d.ts                    |  4 +-
 mw/loader.d.ts                      | 14 +++----
 mw/log.d.ts                         |  9 +++--
 mw/notification.d.ts                |  9 ++++-
 mw/storage.d.ts                     |  2 +-
 mw/util.d.ts                        | 27 +++++++++++--
 28 files changed, 222 insertions(+), 189 deletions(-)

diff --git a/jquery/confirmable.d.ts b/jquery/confirmable.d.ts
index 20843b9..a8c60d7 100644
--- 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
index 6c0d3f9..ecc3e6a 100644
--- 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
index 05df7cc..6b51683 100644
--- 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
index 6154d2a..df8312b 100644
--- 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
index 64e48ac..38ce401 100644
--- a/jquery/makeCollapsible.d.ts
+++ b/jquery/makeCollapsible.d.ts
@@ -2,7 +2,6 @@ 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
@@ -10,6 +9,8 @@ declare global {
          * - 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
index 29f48d7..da410dc 100644
--- 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
index beabc73..164e070 100644
--- 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
index b87bbe0..0d78c5b 100644
--- 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
index 0666398..560d337 100644
--- 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
index a945e65..80a7d41 100644
--- 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
index aa274ee..bd2c787 100644
--- 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
index b4d813f..565e40c 100644
--- 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
index 0cd81e4..4433a9b 100644
--- 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,
diff --git a/mw/Map.d.ts b/mw/Map.d.ts
index f91b62b..6c40c37 100644
--- a/mw/Map.d.ts
+++ b/mw/Map.d.ts
@@ -67,17 +67,34 @@ export interface ExtensibleMap<V extends Record<string, any>, TX = unknown>
 declare global {
     namespace mw {
         /**
-         * ES3 compatible class similar to {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map ES6 Map}.
+         * Collection of values by string keys.
          *
-         * Create an object that can be read from or written to via methods that allow
-         * interaction both with single and multiple properties at once.
+         * This is an internal class that backs the mw.config and mw.messages APIs.
+         *
+         * It allows reading and writing to the collection via public methods,
+         * and allows batch iteraction for all its methods.
+         *
+         * For {@link mw.config}, scripts sometimes choose to "import" a set of keys locally,
+         * like so:
+         *
+         * ```js
+         * var conf = mw.config.get( [ 'wgServerName', 'wgUserName', 'wgPageName' ] );
+         * conf.wgServerName; // "example.org"
+         * ```
+         *
+         * Check the existence ("AND" condition) of multiple keys:
          *
-         * @example
          * ```js
-         * const map = new mw.Map();
-         * map.set( 'foo', 5 );
-         * alert( 5 === map.get( 'foo' ) );
+         * if ( mw.config.exists( [ 'wgFoo', 'wgBar' ] ) );
          * ```
+         *
+         * For mw.messages, the {@link set} method allows {@link mw.loader} and {@link mw.Api} to essentially
+         * extend the object, and batch-apply all their loaded values in one go:
+         *
+         * ```
+         * mw.messages.set( { "mon": "Monday", "tue": "Tuesday" } );
+         * ```
+         *
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.Map.html
          */
         class Map<V extends Record<string, any> = any> {
diff --git a/mw/Rest.d.ts b/mw/Rest.d.ts
index a886aa3..d9f9242 100644
--- a/mw/Rest.d.ts
+++ b/mw/Rest.d.ts
@@ -3,34 +3,36 @@ export type RestResponse = Record<string, any>; // Unknown JSON object
 declare global {
     namespace mw {
         /**
+         * Interact with the REST API. `mw.Rest` is a client library for the
+         * {@link https://www.mediawiki.org/wiki/Special:MyLanguage/API:REST_API REST API}.
+         * An `mw.Rest` object represents the REST API of a MediaWiki site. For the action API, see {@link mw.Api}.
+         *
+         * @example
+         * ```js
+         * var api = new mw.Rest();
+         * api.get( '/v1/page/Main_Page/html' )
+         * .then( function ( data ) {
+         *     console.log( data );
+         * } );
+         *
+         * api.post( '/v1/page/Main_Page', {
+         *     token: 'anon_token',
+         *     source: 'Lörem Ipsüm',
+         *     comment: 'tästing',
+         *     title: 'My_Page'
+         * }, {
+         *     'authorization': 'token'
+         * } )
+         * .then( function ( data ) {
+         *     console.log( data );
+         * } );
+         * ```
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.Rest.html
          */
         class Rest {
             /**
-             * Constructor to create an object to interact with the REST API of a particular
-             * MediaWiki server. mw.Rest objects represent the REST API of a particular
-             * MediaWiki server.
+             * Create an instance of {@link mw.Rest}.
              *
-             * @example
-             * ```js
-             * var api = new mw.Rest();
-             * api.get( '/v1/page/Main_Page/html' )
-             * .done( function ( data ) {
-             *     console.log( data );
-             * } );
-             *
-             * api.post( '/v1/page/Main_Page', {
-             *     token: 'anon_token',
-             *     source: 'Lörem Ipsüm',
-             *     comment: 'tästing',
-             *     title: 'My_Page'
-             * }, {
-             *     'authorization': 'token'
-             * } )
-             * .done( function ( data ) {
-             *     console.log( data );
-             * } );
-             * ```
              * @param {Rest.Options} [options] See {@link mw.Rest.Options}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.Rest.html#Rest
              */
diff --git a/mw/Title.d.ts b/mw/Title.d.ts
index 2941e65..ef49064 100644
--- a/mw/Title.d.ts
+++ b/mw/Title.d.ts
@@ -88,7 +88,7 @@ declare global {
 
             /**
              * Parse titles into an object structure. Note that when using the constructor
-             * directly, passing invalid titles will result in an exception. See {@link newFromText} to use the
+             * directly, passing invalid titles will result in an exception. Use {@link newFromText} to use the
              * logic directly and get null for invalid titles which is easier to work with.
              *
              * @param {string} title Title of the page. If no second argument given,
@@ -209,7 +209,7 @@ declare global {
              * Get the namespace prefix (in the content language).
              *
              * Example: `File:` for `File:Example_image.svg`.
-             * In #NS_MAIN this is '', otherwise namespace name plus ':'
+             * In `NS_MAIN` this is '', otherwise namespace name plus ':'
              *
              * @returns {string}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.Title.html#getNamespacePrefix
diff --git a/mw/Upload.d.ts b/mw/Upload.d.ts
index 589f97a..dda154f 100644
--- a/mw/Upload.d.ts
+++ b/mw/Upload.d.ts
@@ -3,10 +3,9 @@ import { ApiResponse } from "./Api";
 declare global {
     namespace mw {
         /**
-         * Used to represent an upload in progress on the frontend.
-         * Most of the functionality is implemented in mw.Api.plugin.upload,
-         * but this model class will tie it together as well as let you perform
-         * actions in a logical way.
+         * Upload to a wiki. Most of the functionality is implemented
+         * in {@link mw.Api.upload} and friends, but this model class will tie it
+         * together as well as let you perform actions in a logical way.
          *
          * A simple example:
          *
@@ -51,47 +50,6 @@ declare global {
         class Upload {
             /**
              * Used to represent an upload in progress on the frontend.
-             * Most of the functionality is implemented in mw.Api.plugin.upload,
-             * but this model class will tie it together as well as let you perform
-             * actions in a logical way.
-             *
-             * A simple example:
-             *
-             * ```js
-             * var file = new OO.ui.SelectFileWidget(),
-             *     button = new OO.ui.ButtonWidget( { label: 'Save' } ),
-             *     upload = new mw.Upload;
-             *
-             * button.on( 'click', function () {
-             *     upload.setFile( file.getValue() );
-             *     upload.setFilename( file.getValue().name );
-             *     upload.upload();
-             * } );
-             *
-             * $( document.body ).append( file.$element, button.$element );
-             * ```
-             *
-             * You can also choose to {@link uploadToStash stash the upload} and
-             * {@link finishStashUpload finalize} it later:
-             *
-             * ```js
-             * var file, // Some file object
-             *     upload = new mw.Upload,
-             *     stashPromise = $.Deferred();
-             *
-             * upload.setFile( file );
-             * upload.uploadToStash().then( function () {
-             *     stashPromise.resolve();
-             * } );
-             *
-             * stashPromise.then( function () {
-             *     upload.setFilename( 'foo' );
-             *     upload.setText( 'bar' );
-             *     upload.finishStashUpload().then( function () {
-             *         console.log( 'Done!' );
-             *     } );
-             * } );
-             * ```
              *
              * @param {Api|Api.Options} [apiconfig] A mw.Api object (or subclass), or configuration
              *     to pass to the constructor of mw.Api.
diff --git a/mw/Uri.d.ts b/mw/Uri.d.ts
index 4647dfc..e27dbaa 100644
--- a/mw/Uri.d.ts
+++ b/mw/Uri.d.ts
@@ -19,7 +19,7 @@ declare global {
         function UriRelative(documentLocation: string | (() => string)): typeof Uri;
 
         /**
-         * Library for simple URI parsing and manipulation.
+         * Create and manipulate MediaWiki URIs.
          *
          * Intended to be minimal, but featureful; do not expect full RFC 3986 compliance. The use cases we
          * have in mind are constructing 'next page' or 'previous page' URLs, detecting whether we need to
@@ -65,8 +65,8 @@ declare global {
          * fragment  'top'
          * ```
          *
-         * (N.b., 'password' is technically not allowed for HTTP URIs, but it is possible with other kinds
-         * of URIs.)
+         * Note: 'password' is technically not allowed for HTTP URIs, but it is possible with other kinds
+         * of URIs.
          *
          * Parsing based on parseUri 1.2.2 (c) Steven Levithan <http://stevenlevithan.com>, MIT License.
          * <http://stevenlevithan.com/demo/parseuri/js/>
@@ -147,7 +147,8 @@ declare global {
             ];
 
             /**
-             * Create and manipulate MediaWiki URIs.
+             * Construct a new URI object. Throws error if arguments are illegal/impossible, or
+             * otherwise don't parse.
              *
              * @param {string|Uri|Object.<string,string>} [uri] URI string, or an Object with appropriate properties (especially
              *  another URI object to clone). Object must have non-blank `protocol`, `host`, and `path`
diff --git a/mw/cookie.d.ts b/mw/cookie.d.ts
index 9ca7a2a..45976aa 100644
--- a/mw/cookie.d.ts
+++ b/mw/cookie.d.ts
@@ -5,7 +5,6 @@ declare global {
         /**
          * Manage cookies in a way that is syntactically and functionally similar
          * to the `WebRequest#getCookie` and `WebResponse#setcookie` methods in PHP.
-         * Provided by the `mediawiki.cookie` ResourceLoader module.
          *
          * @example
          * ```js
@@ -33,8 +32,9 @@ declare global {
             function get(key: string, prefix?: string | null): string | null;
 
             /**
-             * Get the value of a `SameSite` = `None` cookie, using the legacy `ss0-` prefix if needed.
+             * Get the value of a cookie.
              *
+             * @deprecated since 1.43, use {@link mw.cookie.get} instead
              * @param {string} key The key for the cookie
              * @param {string} [prefix] The prefix of the key. If undefined or null, `$wgCookiePrefix` is used
              * @param {string|null} [defaultValue] A value to return if the cookie does not exist
@@ -46,7 +46,7 @@ declare global {
                 prefix: string | undefined | null,
                 defaultValue: D
             ): string | D;
-            function getCrossSite(key: string, prefix?: string | null): string | undefined;
+            function getCrossSite(key: string, prefix?: string | null): string | null;
 
             /**
              * Set or delete a cookie.
diff --git a/mw/debug.d.ts b/mw/debug.d.ts
index 98de6a8..ce8cdc0 100644
--- a/mw/debug.d.ts
+++ b/mw/debug.d.ts
@@ -36,9 +36,7 @@ interface Query {
 declare global {
     namespace mw {
         /**
-         * Debug toolbar.
-         *
-         * Enabled server-side through `$wgDebugToolbar`.
+         * Access the debug toolbar. Enabled server-side through `$wgDebugToolbar`.
          *
          * @since 1.19
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.Debug.html
diff --git a/mw/hook.d.ts b/mw/hook.d.ts
index 3fc6f27..0295f07 100644
--- a/mw/hook.d.ts
+++ b/mw/hook.d.ts
@@ -14,6 +14,7 @@ import { User } from "./user";
  * Features like navigating to other wiki pages, previewing an edit
  * and editing itself – without a refresh – can then retrigger these
  * hooks accordingly to ensure everything still works as expected.
+ * See {@link Hook}.
  *
  * Example usage:
  *
@@ -38,6 +39,8 @@ import { User } from "./user";
  * new mw.Foo( .. ).fetch( { callback: h.fire } );
  * ```
  *
+ * The function signature for hooks can be considered {@link https://www.mediawiki.org/wiki/Special:MyLanguage/Stable_interface_policy/Frontend stable}.
+ *
  * @see https://doc.wikimedia.org/mediawiki-core/master/js/Hook.html
  */
 interface Hook<T extends any[] = any[]> {
@@ -204,7 +207,7 @@ declare global {
          */
         function hook(
             name: "util.addPortlet"
-        ): Hook<[portlet: HTMLElement, before: string | undefined]>;
+        ): Hook<[portlet: HTMLElement, selectorHint: string | undefined]>;
 
         /**
          * Create an instance of {@link Hook}, fired when a portlet link is successfully created.
diff --git a/mw/index.d.ts b/mw/index.d.ts
index f86bc5f..b2f17c1 100644
--- a/mw/index.d.ts
+++ b/mw/index.d.ts
@@ -76,6 +76,9 @@ declare global {
     /**
      * Base library for MediaWiki.
      *
+     * Exposed globally as `mw`, with `mediaWiki` as alias. `mw` code can be considered stable and follows the
+     * {@link https://www.mediawiki.org/wiki/Special:MyLanguage/Stable_interface_policy/Frontend frontend stable interface policy}.
+     *
      * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.html
      */
     namespace mw {
diff --git a/mw/language.d.ts b/mw/language.d.ts
index 48c197c..092e973 100644
--- a/mw/language.d.ts
+++ b/mw/language.d.ts
@@ -95,7 +95,7 @@ declare global {
             function convertGrammar(word: string, form: string): string;
 
             /**
-             * Converts a number using {@link getDigitTransformTable}.
+             * Converts a number using {@link getDigitTransformTable()}.
              *
              * @param {number} num Value to be converted
              * @param {boolean} [integer=false] Whether to convert the return value to an integer
@@ -195,7 +195,7 @@ declare global {
             /**
              * Convenience method for setting language data.
              *
-             * Creates the data mw.Map if there isn't one for the specified language already.
+             * Creates the data {@link mw.Map} if there isn't one for the specified language already.
              *
              * @param {string} langCode
              * @param {string|Object.<string, any>} dataKey Key or object of key/values
diff --git a/mw/loader.d.ts b/mw/loader.d.ts
index 6805529..c33ea29 100644
--- a/mw/loader.d.ts
+++ b/mw/loader.d.ts
@@ -142,7 +142,7 @@ declare global {
              *
              * - `registered`: The module is available for loading but not yet requested.
              * - `loading`, `loaded`, or `executing`: The module is currently being loaded.
-             * - `ready`: The module was succesfully and fully loaded.
+             * - `ready`: The module was successfully and fully loaded.
              * - `error`: The module or one its dependencies has failed to load, e.g. due to
              *    uncaught error from the module's script files.
              * - `missing`: The module was requested but is not defined according to the server.
@@ -151,19 +151,19 @@ declare global {
              *
              * - `registered`:
              *    The module is known to the system but not yet required.
-             *    Meta data is stored by {@link mw.loader.register}.
+             *    Meta data is stored by {@link register()}.
              *    Calls to that method are generated server-side by StartupModule.
              * - `loading`:
              *    The module was required through mw.loader (either directly or as dependency of
-             *    another module). The client will fetch module contents from mw.loader.store
-             *    or from the server. The contents should later be received by {@link mw.loader.implement}.
+             *    another module). The client will fetch module contents from {@link mw.loader.store}
+             *    or from the server. The contents should later be received by {@link implement()}.
              * - `loaded`:
-             *    The module has been received by mw.loader#implement.
+             *    The module has been received by {@link implement()}.
              *    Once the module has no more dependencies in-flight, the module will be executed,
-             *    controlled via #setAndPropagate and #doPropagation.
+             *    controlled via `setAndPropagate()` and `doPropagation()`.
              * - `executing`:
              *    The module is being executed (apply messages and stylesheets, execute scripts)
-             *    by mw.loader#execute.
+             *    by `execute()`.
              * - `ready`:
              *    The module has been successfully executed.
              * - `error`:
diff --git a/mw/log.d.ts b/mw/log.d.ts
index ed17f5e..82c633e 100644
--- a/mw/log.d.ts
+++ b/mw/log.d.ts
@@ -3,17 +3,20 @@ declare global {
         /**
          * Write a verbose message to the browser's console in debug mode.
          *
-         * This method is mainly intended for verbose logging. It is a no-op in production mode.
-         * In ResourceLoader debug mode, it will use the browser's console.
+         * In ResourceLoader debug mode, this writes to the browser's console.
+         * In production mode, it is a no-op.
          *
          * See {@link mw.log} for other logging methods.
          *
+         * @variation 2
          * @param {...any} msg Messages to output to console.
          */
         function log(...msg: any[]): void;
 
         /**
-         * Library for logging developer warnings to the JavaScript console.
+         * Log debug messages and developer warnings to the browser console.
+         *
+         * See {@link mw.log(2) mw.log()} for verbose debug logging.
          *
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.log.html
          */
diff --git a/mw/notification.d.ts b/mw/notification.d.ts
index de8be0c..cc58f0e 100644
--- a/mw/notification.d.ts
+++ b/mw/notification.d.ts
@@ -89,10 +89,17 @@ declare global {
             const autoHideLimit: number;
 
             /**
-             * @private
+             * Map of predefined auto-hide timeout keys to second values. `short` is
+             * used by default, and other values can be added for use in {@link notify}.
              */
             const autoHideSeconds: {
+                /**
+                 * 5 seconds (default).
+                 */
                 long: number;
+                /**
+                 * 30 seconds.
+                 */
                 short: number;
             };
 
diff --git a/mw/storage.d.ts b/mw/storage.d.ts
index f3f2b30..714ef5f 100644
--- a/mw/storage.d.ts
+++ b/mw/storage.d.ts
@@ -122,7 +122,7 @@ interface MwStorage extends SafeStorage {
      * to know about and delete when the data is no longer needed. Instead,
      * store dynamic values in an object under a single constant key that you
      * manage or replace over time.
-     * See also {@link https://phabricator.wikimedia.org/T121646}.
+     * See also {@link https://phabricator.wikimedia.org/T121646 T121646}.
      *
      * @example
      * ```js
diff --git a/mw/util.d.ts b/mw/util.d.ts
index c2a7c0f..85d5cc6 100644
--- a/mw/util.d.ts
+++ b/mw/util.d.ts
@@ -99,17 +99,36 @@ declare global {
             /**
              * Creates a detached portlet Element in the skin with no elements.
              *
+             * @example
+             * ```js
+             * // Create a portlet with 2 menu items that is styled as a dropdown in certain skins.
+             * const p = mw.util.addPortlet( 'p-myportlet', 'My label', '#p-cactions' );
+             * mw.util.addPortletLink( 'p-myportlet', '#', 'Link 1' );
+             * mw.util.addPortletLink( 'p-myportlet', '#', 'Link 2' );
+             * ```
              * @since 1.41
              * @param {string} id of the new portlet.
              * @param {string} [label] of the new portlet.
-             * @param {string} [before] selector of the element preceding the new portlet. If not passed
-             *  the caller is responsible for appending the element to the DOM before using addPortletLink.
+             * @param {string} [selectorHint] selector of the element the new portlet would like to
+             *  be inserted near. Typically the portlet will be inserted after this selector, but in some
+             *  skins, the skin may relocate the element when provided to the closest available space.
+             *  If this argument is not passed then the caller is responsible for appending the element
+             *  to the DOM before using addPortletLink.
+             *  To add a portlet in an exact position do not rely on this parameter, instead using the return
+             *  element (make sure to also assign the result to a variable), use `p.parentNode.appendChild( p );`.
+             *  When provided, skins can use the parameter to infer information about how the user intended
+             *  the menu to be rendered. For example, in vector and vector-2022 targeting '#p-cactions' will
+             *  result in the creation of a dropdown.
              * @returns {HTMLElement|null} will be null if it was not possible to create an portlet with
-             *  the required information e.g. the selector given in before parameter could not be resolved
+             *  the required information e.g. the selector given in `selectorHint` parameter could not be resolved
              *  to an existing element in the page.
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/module-mediawiki.util.html#.addPortlet
              */
-            function addPortlet(id: string, label?: string, before?: string): HTMLElement | null;
+            function addPortlet(
+                id: string,
+                label?: string,
+                selectorHint?: string
+            ): HTMLElement | null;
 
             /**
              * Add a link to a portlet menu on the page.