From 7e1e8312a50338a959777c7a72bd35d0e0543e10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adrien=20LES=C3=89N=C3=89CHAL?= Date: Tue, 30 Jan 2024 11:03:50 +0100 Subject: [PATCH] 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 --- mw/Api.d.ts | 26 +++++++++++++++++--------- mw/ForeignApi.d.ts | 6 +++--- mw/ForeignRest.d.ts | 4 ++-- mw/RegExp.d.ts | 4 ++-- mw/Rest.d.ts | 2 +- mw/Title.d.ts | 1 + mw/Uri.d.ts | 29 ++++++++++++++++++----------- mw/experiments.d.ts | 5 +++-- mw/html.d.ts | 2 +- mw/index.d.ts | 24 +++++++++++++++--------- mw/language.d.ts | 28 +++++++++++----------------- mw/loader.d.ts | 12 +++++------- mw/notification.d.ts | 10 +++++++--- mw/storage.d.ts | 5 ++--- mw/user.d.ts | 8 ++++---- 15 files changed, 92 insertions(+), 74 deletions(-) diff --git a/mw/Api.d.ts b/mw/Api.d.ts index 10bc406..d9057dd 100644 --- 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} - * @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} 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; @@ -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} @@ -370,6 +373,7 @@ declare global { /** * Get the current user's groups and rights. * + * @since 1.27 * @returns {JQuery.Promise} * @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} * @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.} options Options as a `{ name: value, … }` object * @returns {JQuery.Promise} * @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} pages * @param {string} [expiry] * @returns {JQuery.Promise<{ watch: TypeOrArray }>} - * @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

>( @@ -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} * @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; /** * 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} * @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; /** * 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} @@ -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 index 0f04cdd..7d0a98a 100644 --- a/mw/ForeignApi.d.ts +++ b/mw/ForeignApi.d.ts @@ -38,9 +38,9 @@ declare global { * mw.ForeignApi = MyForeignApi; * ``` * - * @param {string | Uri} url URL pointing to another wiki's `api.php` endpoint. - * @param {Partial} [options] * @since 1.26 + * @param {string|Uri} url URL pointing to another wiki's `api.php` endpoint. + * @param {Partial} [options] * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignApi-method-constructor */ constructor(url: string | Uri, options?: Partial); @@ -48,8 +48,8 @@ declare global { /** * 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 index cf327f1..c1ecaa7 100644 --- 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} [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 index 6966c7d..b66cc1a 100644 --- 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 index df5919f..483c0f5 100644 --- a/mw/Rest.d.ts +++ b/mw/Rest.d.ts @@ -35,7 +35,7 @@ declare global { * } ); * ``` * - * @param {RestOptions} [options] + * @param {Partial} [options] * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Rest-method-constructor */ constructor(options?: Partial); diff --git a/mw/Title.d.ts b/mw/Title.d.ts index c52b282..b03910d 100644 --- 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 index 52213d0..f748e3b 100644 --- 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|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} 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 index 3dcbe37..7b3d71e 100644 --- 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.} 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 index 289805d..30b8d49 100644 --- 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.} [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 index 27de9fb..f7b395b 100644 --- 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; @@ -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; diff --git a/mw/language.d.ts b/mw/language.d.ts index f84829c..8c078f5 100644 --- a/mw/language.d.ts +++ b/mw/language.d.ts @@ -46,7 +46,6 @@ declare global { * - `bcp47Map` * - `languageNames` * - * @property {Object} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-property-data */ const data: Record; @@ -54,7 +53,6 @@ declare global { /** * Information about month names in current UI language. * - * @property {Object} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-property-months */ const months: { @@ -68,11 +66,7 @@ declare global { * Object containing zero-indexed arrays of message keys for appropriate messages * which can be passed to {@link mw.msg}. */ - keys: { - abbrev: string[]; - genitive: string[]; - names: string[]; - }; + keys: Record<"abbrev" | "genitive" | "names", string[]>; /** * Array of month names in genitive case, zero-indexed. @@ -124,8 +118,8 @@ declare global { * Plural form transformations, needed for some languages. * * @param {number} count Non-localized quantifier - * @param {Array} forms List of plural forms - * @param {Object} [explicitPluralForms] List of explicit plural forms + * @param {string[]} forms List of plural forms + * @param {Object.} [explicitPluralForms] List of explicit plural forms * @returns {string} Correct form for quantifier in this language * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-convertPlural */ @@ -138,8 +132,8 @@ declare global { /** * Helper function to flip transformation tables. * - * @param {...Object} tables Transformation tables - * @returns {Object} + * @param {...Object.} tables Transformation tables + * @returns {Object.} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-flipTransform */ function flipTransform>( @@ -155,7 +149,7 @@ declare global { * These details may be overridden per language. * * @param {string} gender 'male', 'female', or anything else for neutral. - * @param {Array} forms List of gender forms + * @param {string[]} forms List of gender forms * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-gender */ @@ -178,7 +172,7 @@ declare global { /** * Get the digit transform table for current UI language. * - * @returns {Object|Array} + * @returns {Object.|string[]} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-getDigitTransformTable */ function getDigitTransformTable(): string[] | Record; @@ -202,7 +196,7 @@ declare global { /** * Get the separator transform table for current UI language. * - * @returns {Object|Array} + * @returns {Object.|string[]} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-getSeparatorTransformTable */ function getSeparatorTransformTable(): string[] | Record; @@ -224,7 +218,7 @@ declare global { * Creates the data mw.Map if there isn't one for the specified language already. * * @param {string} langCode - * @param {string|Object} dataKey Key or object of key/values + * @param {string|Object.} dataKey Key or object of key/values * @param {Mixed} [value] Value for dataKey, omit if dataKey is an object * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-setData */ @@ -277,9 +271,9 @@ declare global { * Pads an array to a specific length by copying the last one element. * * @private - * @param {Array} forms Number of forms given to convertPlural + * @param {string[]} forms Number of forms given to convertPlural * @param {number} count Number of forms required - * @returns {Array} Padded array of forms + * @returns {string[]} Padded array of forms * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-preConvertPlural */ function preConvertPlural(forms: string[], count: number): string[]; diff --git a/mw/loader.d.ts b/mw/loader.d.ts index ae416c2..a0dd49d 100644 --- a/mw/loader.d.ts +++ b/mw/loader.d.ts @@ -236,7 +236,7 @@ declare global { * - This method is used for preloading, which must not throw. Later code that * calls {@link using()} will handle the error. * - * @param {string|Array} modules Either the name of a module, array of modules, + * @param {string|string[]} modules Either the name of a module, array of modules, * or a URL of an external script or style * @param {string} [type='text/javascript'] MIME type to use if calling with a URL of an * external script or style; acceptable values are "text/css" and @@ -289,7 +289,7 @@ declare global { /** * Change the state of one or more modules. * - * @param {Object} states Object of module name/state pairs + * @param {Object.} states Object of module name/state pairs * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.loader-method-state */ function state(states: Record): void; @@ -328,11 +328,11 @@ declare global { * * Since MediaWiki 1.28 the promise is resolved with a `require` function. * - * @param {string|Array} dependencies Module name or array of modules names the + * @param {string|string[]} dependencies Module name or array of modules names the * callback depends on to be ready before executing * @param {Function} [ready] Callback to execute when all dependencies are ready * @param {Function} [error] Callback to execute if one or more dependencies failed - * @returns {JQuery.Promise} With a `require` function + * @returns {JQuery.Promise} With a `require` function * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.loader-method-using */ function using( @@ -345,7 +345,6 @@ declare global { * Exposed for testing and debugging only. * * @private - * @property {number} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.loader-property-maxQueryLength */ const maxQueryLength: number; @@ -355,7 +354,6 @@ declare global { * state; it is not a public interface for modifying the registry. * * @private - * @property {Object} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.loader-property-moduleRegistry */ const moduleRegistry: Record; @@ -431,7 +429,7 @@ declare global { * * @private * @param {string[]} modules Array of string module names - * @returns {Array} List of dependencies, including 'module'. + * @returns {string[]} List of dependencies, including 'module'. * @throws {Error} If an unregistered module or a dependency loop is encountered * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.loader-method-resolve */ diff --git a/mw/notification.d.ts b/mw/notification.d.ts index d0f53dc..0d18a18 100644 --- a/mw/notification.d.ts +++ b/mw/notification.d.ts @@ -111,9 +111,9 @@ declare global { * Display a notification message to the user. * * @param {HTMLElement|HTMLElement[]|JQuery|Message|string} message - * @param {Object} [options] The options to use for the notification. + * @param {Partial} [options] The options to use for the notification. * See {@link NotificationOptions defaults} for details. - * @returns {JQuery.Promise} Notification object + * @returns {JQuery.Promise} Notification object * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-notify */ function notify( @@ -138,6 +138,10 @@ declare global { */ const autoHideLimit: number; + /** + * @private + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.notification-property-autoHideSeconds + */ const autoHideSeconds: { short: number; long: number; @@ -170,7 +174,7 @@ declare global { * Display a notification message to the user. * * @param {HTMLElement|HTMLElement[]|JQuery|Message|string} message - * @param {Object} [options] The options to use for the notification. + * @param {Partial} [options] The options to use for the notification. * See {@link NotificationOptions defaults} for details. * @returns {Notification} Notification object * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.notification-method-notify diff --git a/mw/storage.d.ts b/mw/storage.d.ts index c8be39e..7a68de7 100644 --- a/mw/storage.d.ts +++ b/mw/storage.d.ts @@ -3,7 +3,6 @@ * that is safe to call in all browsers. * * @private - * @param {Object|undefined} store The Storage instance to wrap around * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.SafeStorage */ interface SafeStorage { @@ -11,7 +10,7 @@ interface SafeStorage { * Retrieve value from device storage. * * @param {string} key Key of item to retrieve - * @returns {string|null|boolean} String value, null if no value exists, or false + * @returns {string|null|false} String value, null if no value exists, or false * if storage is not available. * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.SafeStorage-method-get */ @@ -83,7 +82,7 @@ interface SafeStorage { * Get all keys with expiry values * * @private - * @returns {JQuery.Promise} Promise resolving with all the keys which have + * @returns {JQuery.Promise} Promise resolving with all the keys which have * expiry values (unprefixed), or as many could be retrieved in the allocated time. * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.SafeStorage-method-getExpiryKeys */ diff --git a/mw/user.d.ts b/mw/user.d.ts index c09499c..cf73cef 100644 --- a/mw/user.d.ts +++ b/mw/user.d.ts @@ -36,7 +36,7 @@ export interface User { * will be used for their account. It may also be used in previews. However, the account is not * created yet, and the name is not visible to other users. * - * @returns {JQuery.Promise} Promise resolved with the username if we succeeded, + * @returns {JQuery.Promise} Promise resolved with the username if we succeeded, * or resolved with `null` if we failed * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.user-method-acquireTempUserName */ @@ -71,7 +71,7 @@ export interface User { * Get the current user's groups * * @param {Function} [callback] - * @returns {JQuery.Promise} + * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.user-method-getGroups */ getGroups(callback: (groups: string[]) => T): JQuery.Promise; @@ -118,7 +118,7 @@ export interface User { * Get the current user's rights * * @param {Function} [callback] - * @returns {JQuery.Promise} + * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.user-method-getRights */ getRights(callback: (rights: string[]) => T): JQuery.Promise; @@ -176,7 +176,7 @@ export interface User { * Get the current user's groups or rights * * @private - * @returns {JQuery.Promise} + * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.user-method-getUserInfo */ getUserInfo(): JQuery.Promise;