Doc & type fixes

From reviews & comments by @AnYiEE - add missing `@see`/`@since` annotations - fix `mw.Api.getMessages`/`loadMessages` not allowing `string` as parameter - fix `mw.format` to only accept string parameters - add missing `options` argument to `mw.requestIdleCallback` - remove redundant `@property`/`@protected` annotations
wikimedia-gadgets · Jan 30, 2024 · 7e1e831 · 7e1e831
1 parent f0c3364
commit 7e1e831
Show file tree

Hide file tree

Showing 15 changed files with 92 additions and 74 deletions.
diff --git a/mw/Api.d.ts b/mw/Api.d.ts
@@ -136,6 +136,7 @@ declare global {
              *
              * @param {ApiParams} parameters (modified in-place)
              * @param {boolean} useUS Whether to use U+001F when joining multi-valued parameters.
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-preprocessParameters
              */
             private preprocessParameters(parameters: ApiParams, useUS: boolean): void;
 
@@ -165,11 +166,11 @@ declare global {
              * } );
              * ```
              *
+             * @since 1.22
              * @param {string} tokenType The name of the token, like `options` or `edit`
              * @param {ApiParams} params API parameters
              * @param {JQuery.AjaxSettings} [ajaxOptions]
              * @returns {JQuery.Promise<ApiResponse>}
-             * @since 1.22
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-postWithToken
              */
             postWithToken(
@@ -181,10 +182,10 @@ declare global {
             /**
              * Get a token for a certain action from the API.
              *
+             * @since 1.22
              * @param {string} type Token type
              * @param {ApiParams|string} [additionalParams] Additional parameters for the API (since 1.35). When given a string, it's treated as the `assert` parameter (since 1.25)
              * @returns {JQuery.Promise<string>} Received token
-             * @since 1.22
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-getToken
              */
             getToken(type: string, additionalParams?: ApiParams | string): JQuery.Promise<string>;
@@ -196,8 +197,8 @@ declare global {
              * You may also want to use `postWithToken()` instead, which invalidates bad cached tokens
              * automatically.
              *
-             * @param {string} type Token type
              * @since 1.26
+             * @param {string} type Token type
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-badToken
              */
             badToken(type: string): void;
@@ -273,6 +274,7 @@ declare global {
              * );
              * ```
              *
+             * @since 1.28
              * @param {TitleLike} title Page title
              * @param {ApiEditPageParams} params Edit API parameters
              * @param {string} content Page content
@@ -340,6 +342,7 @@ declare global {
              *     } );
              * ```
              *
+             * @since 1.28
              * @param {TitleLike} title Page title
              * @param {function(Revision):string|ApiEditPageParams} transform Callback that prepares the edit
              * @returns {JQuery.Promise<any>}
@@ -370,6 +373,7 @@ declare global {
             /**
              * Get the current user's groups and rights.
              *
+             * @since 1.27
              * @returns {JQuery.Promise<UserInfo>}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.user-method-getUserInfo
              */
@@ -385,6 +389,7 @@ declare global {
              * * `apierror-assertuserfailed`: when the client-side logic thinks the user is logged in but the server thinks it is anonymous
              * * `apierror-assertnameduserfailed`: when both the client-side logic and the server thinks the user is logged in but they see it logged in under a different username.
              *
+             * @since 1.27
              * @param {ApiParams} query Query parameters. The object will not be changed
              * @returns {JQuery.Promise<AssertUser>}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.user-method-assertCurrentUser
@@ -412,7 +417,7 @@ declare global {
              *
              * If a request from a previous `saveOptions()` call is still pending, this will wait for it to be completed, otherwise MediaWiki gets sad. No requests are sent for anonymous users, as they would fail anyway. See T214963.
              *
-             * @param {Object} options Options as a `{ name: value, … }` object
+             * @param {Object.<string, string|null>} options Options as a `{ name: value, … }` object
              * @returns {JQuery.Promise<ApiResponse>}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.options-method-saveOptions
              */
@@ -421,10 +426,10 @@ declare global {
             /**
              * Convenience method for `action=watch`.
              *
+             * @since 1.35 - expiry parameter can be passed when Watchlist Expiry is enabled
              * @param {TypeOrArray<TitleLike>} pages
              * @param {string} [expiry]
              * @returns {JQuery.Promise<{ watch: TypeOrArray<WatchStatus> }>}
-             * @since 1.35: expiry parameter can be passed when watchlist expiry is enabled
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.watch-method-watch
              */
             watch<P extends TypeOrArray<TitleLike>>(
@@ -457,32 +462,34 @@ declare global {
             /**
              * Get a set of messages.
              *
-             * @param {string[]} messages Messages to retrieve
+             * @since 1.27
+             * @param {string|string[]} messages Messages to retrieve
              * @param {ApiQueryAllMessagesParams} [options] Additional parameters for the API call
              * @returns {JQuery.Promise<ApiResponse>}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.messages-method-getMessages
              */
             getMessages(
-                messages: string[],
+                messages: string | string[],
                 options?: ApiQueryAllMessagesParams
             ): JQuery.Promise<ApiResponse>;
 
             /**
              * Load a set of messages and add them to `mw.messages`.
              *
-             * @param {string[]} messages Messages to retrieve
+             * @param {string|string[]} messages Messages to retrieve
              * @param {ApiQueryAllMessagesParams} [options] Additional parameters for the API call
              * @returns {JQuery.Promise<ApiResponse>}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.messages-method-loadMessages
              */
             loadMessages(
-                messages: string[],
+                messages: string | string[],
                 options?: ApiQueryAllMessagesParams
             ): JQuery.Promise<ApiResponse>;
 
             /**
              * Load a set of messages and add them to `mw.messages`. Only messages that are not already known are loaded. If all messages are known, the returned promise is resolved immediately.
              *
+             * @since 1.27
              * @param {string[]} messages Messages to retrieve
              * @param {ApiQueryAllMessagesParams} [options] Additional parameters for the API call
              * @returns {JQuery.Promise<ApiResponse>}
@@ -525,6 +532,7 @@ declare global {
             /**
              * Convenience method for `action=rollback`.
              *
+             * @since 1.28
              * @param {TitleLike} page
              * @param {string} user
              * @param {ApiRollbackParams} [params] Additional parameters

diff --git a/mw/ForeignApi.d.ts b/mw/ForeignApi.d.ts
@@ -38,18 +38,18 @@ declare global {
              * mw.ForeignApi = MyForeignApi;
              * ```
              *
-             * @param {string | Uri} url URL pointing to another wiki's `api.php` endpoint.
-             * @param {Partial<ForeignApiOptions>} [options]
              * @since 1.26
+             * @param {string|Uri} url URL pointing to another wiki's `api.php` endpoint.
+             * @param {Partial<ForeignApiOptions>} [options]
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignApi-method-constructor
              */
             constructor(url: string | Uri, options?: Partial<ForeignApiOptions>);
 
             /**
              * Return the origin to use for API requests, in the required format (protocol, host and port, if any).
              *
-             * @protected
              * @returns {string|undefined}
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignApi-method-getOrigin
              */
             protected getOrigin(): string | undefined;
         }

diff --git a/mw/ForeignRest.d.ts b/mw/ForeignRest.d.ts
@@ -41,11 +41,11 @@ declare global {
              * mw.ForeignRest = MyForeignRest;
              * ```
              *
+             * @since 1.36
              * @param {string} url URL pointing to another wiki's `rest.php` endpoint.
              * @param {ForeignApi} foreignActionApi
              * @param {Partial<ForeignRestOptions>} [options]
-             * @since 1.36
-             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignApi-method-constructor
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignRest-method-constructor
              */
             constructor(
                 url: string,

diff --git a/mw/RegExp.d.ts b/mw/RegExp.d.ts
@@ -11,8 +11,8 @@ declare global {
              *
              *     \ { } ( ) | . ? * + - ^ $ [ ]
              *
-             * @deprecated
-             * @since 1.26; deprecated since 1.34
+             * @deprecated since 1.34
+             * @since 1.26
              * @param {string} str String to escape
              * @returns {string} Escaped string
              * @see https://doc.wikimedia.org/mediawiki-core/REL1_29/js/source/mediawiki.RegExp.html#mw-RegExp-static-method-escape

diff --git a/mw/Rest.d.ts b/mw/Rest.d.ts
@@ -35,7 +35,7 @@ declare global {
              * } );
              * ```
              *
-             * @param {RestOptions} [options]
+             * @param {Partial<RestOptions>} [options]
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Rest-method-constructor
              */
             constructor(options?: Partial<RestOptions>);

diff --git a/mw/Title.d.ts b/mw/Title.d.ts
@@ -27,6 +27,7 @@ declare global {
          * mw.Title.makeTitle( NS_TEMPLATE, 'Template:Foo' ).getPrefixedText();   // => 'Template:Template:Foo'
          * ```
          *
+         * @since 1.18
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title
          */
         class Title {

diff --git a/mw/Uri.d.ts b/mw/Uri.d.ts
@@ -92,42 +92,50 @@ declare global {
          */
         class Uri {
             /**
-             * @property {string|undefined} fragment For example `top`
+             * For example `top`
+             *
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-fragment
              */
             fragment: string | undefined;
             /**
-             * @property {string} host For example `www.example.com` (always present)
+             * For example `www.example.com` (always present)
+             *
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-host
              */
             host: string;
             /**
-             * @property {string|undefined} password For example `pwd`
+             * For example `pwd`
+             *
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-password
              */
             password: string | undefined;
             /**
-             * @property {string} path For example `/dir/dir.2/index.htm` (always present)
+             * For example `/dir/dir.2/index.htm` (always present)
+             *
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-path
              */
             path: string;
             /**
-             * @property {string|undefined} port For example `81`
+             * For example `81`
+             *
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-port
              */
             port: string | undefined;
             /**
-             * @property {string} protocol For example `http` (always present)
+             * For example `http` (always present)
+             *
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-protocol
              */
             protocol: string;
             /**
-             * @property {Object} query For example `{ a: '0', b: '', c: 'value' }` (always present)
+             * For example `{ a: '0', b: '', c: 'value' }` (always present)
+             *
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-query
              */
             query: QueryParams;
             /**
-             * @property {string|undefined} user For example `usr`
+             * For example `usr`
+             *
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-user
              */
             user: string | undefined;
@@ -146,7 +154,6 @@ declare global {
             /**
              * The order here matches the order of captured matches in the `parser` property regexes.
              *
-             * @property {string[]} properties
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-static-property-properties
              */
             private static properties: [
@@ -169,7 +176,7 @@ declare global {
              *  properties. If omitted (or set to `undefined`, `null` or empty string), then an object
              *  will be created for the default `uri` of this constructor (`location.href` for mw.Uri,
              *  other values for other instances -- see mw.UriRelative for details).
-             * @param {Object|boolean} [options] Object with options, or (backwards compatibility) a boolean
+             * @param {Partial<UriOptions>|boolean} [options] Object with options, or (backwards compatibility) a boolean
              *  for strictMode
              * @throws {Error} when the query string or fragment contains an unknown % sequence
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-constructor
@@ -261,7 +268,7 @@ declare global {
              * Parse a string and set our properties accordingly.
              *
              * @param {string} str URI, see constructor.
-             * @param {Object} options See constructor.
+             * @param {Partial<UriOptions>} options See constructor.
              * @throws {Error} when the query string or fragment contains an unknown % sequence
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-parse
              */

diff --git a/mw/experiments.d.ts b/mw/experiments.d.ts
@@ -41,16 +41,17 @@ declare global {
              * }
              * ```
              *
-             * @param {Object} experiment
+             * @param {Experiment} experiment
              * @param {string} experiment.name The name of the experiment
              * @param {boolean} experiment.enabled Whether or not the experiment is
              *  enabled. If the experiment is disabled, then the user is always assigned
              *  to the control bucket
-             * @param {Object} experiment.buckets A map of bucket name to probability
+             * @param {Object.<string, number>} experiment.buckets A map of bucket name to probability
              *  that the user will be assigned to that bucket
              * @param {string} token A token that uniquely identifies the user for the
              *  duration of the experiment
              * @returns {string|undefined} The bucket
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.experiments-method-getBucket
              */
             function getBucket(experiment: Experiment, token: string): string | undefined;
         }

diff --git a/mw/html.d.ts b/mw/html.d.ts
@@ -20,7 +20,7 @@ declare global {
              * Create an HTML element string, with safe escaping.
              *
              * @param {string} name The tag name.
-             * @param {Object} [attrs] An object with members mapping element names to values
+             * @param {Object.<string, string|number|boolean>} [attrs] An object with members mapping element names to values
              * @param {string|Raw|null} [contents=null] The contents of the element.
              *
              *  - string: Text to be escaped.

diff --git a/mw/index.d.ts b/mw/index.d.ts
@@ -61,6 +61,8 @@ declare global {
          * Empty object for third-party libraries, for cases where you don't
          * want to add a new global, or the global is bad and needs containment
          * or wrapping.
+         *
+         * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-property-libs
          */
         const libs: Record<string, any>;
 
@@ -80,11 +82,11 @@ declare global {
          *
          * @since 1.25
          * @param {string} formatString Format string
-         * @param {...Mixed} parameters Values for $N replacements
+         * @param {...string} parameters Values for $N replacements
          * @returns {string} Formatted string
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-format
          */
-        function format(formatString: string, ...parameters: unknown[]): string;
+        function format(formatString: string, ...parameters: string[]): string;
 
         /**
          * Get the current time, measured in milliseconds since January 1, 1970 (UTC).
@@ -126,8 +128,12 @@ declare global {
          * @param {number} [options.timeout] If set, the callback will be scheduled for
          *  immediate execution after this amount of time (in milliseconds) if it didn't run
          *  by that time.
+         * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-requestIdleCallback
          */
-        function requestIdleCallback(callback: (...args: any[]) => any): void;
+        function requestIdleCallback(
+            callback: (...args: any[]) => any,
+            options?: { timeout?: number }
+        ): void;
 
         /**
          * Track an analytic event.
@@ -143,7 +149,7 @@ declare global {
          * was subscribed.
          *
          * @param {string} topic Topic name
-         * @param {Object|number|string} [data] Data describing the event.
+         * @param {AnalyticEventData} [data] Data describing the event.
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-track
          */
         function track(topic: string, data?: AnalyticEventData): void;
@@ -153,7 +159,7 @@ declare global {
          *
          * @private
          * @param {string} topic Topic name
-         * @param {Object} data Data describing the event, encoded as an object; see {@link errorLogger.logError}
+         * @param {ErrorAnalyticEventData} data Data describing the event, encoded as an object; see {@link errorLogger.logError}
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-trackError
          */
         function trackError(topic: string, data: ErrorAnalyticEventData): void;
@@ -179,16 +185,16 @@ declare global {
          * ```
          *
          * @param {string} topic Handle events whose name starts with this string prefix
-         * @param {Function} callback Handler to call for each matching tracked event
-         * @param {string} callback.topic
-         * @param {Object} [callback.data]
+         * @param {function(string, AnalyticEventData): void} callback Handler to call for each matching tracked event
+         * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-trackSubscribe
          */
         function trackSubscribe(topic: string, callback: AnalyticEventCallback): void;
 
         /**
          * Stop handling events for a particular handler
          *
-         * @param {Function} callback
+         * @param {function(string, AnalyticEventData): void} callback
+         * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-trackUnsubscribe
          */
         function trackUnsubscribe(callback: AnalyticEventCallback): void;