From 0ea86ed0138799d8eeb5f48da3f343cc6f2759ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adrien=20LES=C3=89N=C3=89CHAL?= Date: Wed, 28 Feb 2024 15:16:37 +0100 Subject: [PATCH] Small fixes - add missing `@example` annotations - update `mw.Api` comments - make `mw.language.months` a namespace, for the same extensibility reason as with `mw.log` - remove remaining @fires annotations --- mw/Api.d.ts | 54 ++++++++++++++++++++++++++++------------ mw/Rest.d.ts | 2 +- mw/experiments.d.ts | 1 + mw/html.d.ts | 1 + mw/language.d.ts | 60 ++++++++++++++++++++++----------------------- mw/loader.d.ts | 1 + mw/log.d.ts | 1 - mw/message.d.ts | 2 ++ mw/util.d.ts | 1 - tslint.json | 1 - 10 files changed, 75 insertions(+), 49 deletions(-) diff --git a/mw/Api.d.ts b/mw/Api.d.ts index 0819985..a391580 100644 --- a/mw/Api.d.ts +++ b/mw/Api.d.ts @@ -80,6 +80,9 @@ interface RollbackInfo { interface FinishUpload { /** * Call this function to finish the upload. + * + * @param {ApiUploadParams} data Additional data for the upload. + * @returns {JQuery.Promise} API promise for the final upload. */ (data?: ApiUploadParams): JQuery.Promise; } @@ -154,7 +157,7 @@ declare global { abort(): void; /** - * Perform API get request. + * Perform API get request. See {@link ajax()} for details. * * @param {UnknownApiParams} parameters * @param {JQuery.AjaxSettings} [ajaxOptions] @@ -167,7 +170,7 @@ declare global { ): JQuery.Promise; /** - * Perform API post request. + * Perform API post request. See {@link ajax()} for details. * * @param {UnknownApiParams} parameters * @param {JQuery.AjaxSettings} [ajaxOptions] @@ -191,9 +194,30 @@ declare global { /** * Perform the API call. * - * @param {UnknownApiParams} parameters - * @param {JQuery.AjaxSettings} [ajaxOptions] - * @returns {JQuery.Promise} API response data and the jqXHR object + * @param {UnknownApiParams} parameters Parameters to the API. See also {@link ApiOptions.parameters} + * @param {JQuery.AjaxSettings} [ajaxOptions] Parameters to pass to jQuery.ajax. See also {@link ApiOptions.ajax} + * @returns {JQuery.Promise} A promise that settles when the API response is processed. + * Has an 'abort' method which can be used to abort the request. + * + * - On success, resolves to `( result, jqXHR )` where `result` is the parsed API response. + * - On an API error, rejects with `( code, result, result, jqXHR )` where `code` is the + * [API error code](https://www.mediawiki.org/wiki/API:Errors_and_warnings), and `result` + * is as above. When there are multiple errors, the code from the first one will be used. + * If there is no error code, "unknown" is used. + * - On other types of errors, rejects with `( 'http', details )` where `details` is an object + * with three fields: `xhr` (the jqXHR object), `textStatus`, and `exception`. + * The meaning of the last two fields is as follows: + * - When the request is aborted (the abort method of the promise is called), textStatus + * and exception are both set to "abort". + * - On a network timeout, textStatus and exception are both set to "timeout". + * - On a network error, textStatus is "error" and exception is the empty string. + * - When the HTTP response code is anything other than 2xx or 304 (the API does not + * use such response codes but some intermediate layer might), textStatus is "error" + * and exception is the HTTP status text (the text following the status code in the + * first line of the server response). For HTTP/2, `exception` is always an empty string. + * - When the response is not valid JSON but the previous error conditions aren't met, + * textStatus is "parsererror" and exception is the exception object thrown by + * `JSON.parse`. * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-ajax */ ajax( @@ -202,9 +226,9 @@ declare global { ): JQuery.Promise; /** - * Post to API with specified type of token. If we have no token, get one and try to post. - * If we have a cached token try using that, and if it fails, blank out the - * cached token and start over. For example to change an user option you could do: + * Post to API with the specified type of token. If we have no token, get one and try to post. + * If we already have a cached token, try using that, and if the request fails using the cached token, + * blank it out and start over. For example, to change a user option, you could do: * * ```js * new mw.Api().postWithToken( 'csrf', { @@ -215,10 +239,10 @@ declare global { * ``` * * @since 1.22 - * @param {string} tokenType The name of the token, like `options` or `edit` + * @param {string} tokenType The name of the token, like `options` or `edit`. * @param {UnknownApiParams} params API parameters * @param {JQuery.AjaxSettings} [ajaxOptions] - * @returns {JQuery.Promise} + * @returns {JQuery.Promise} See {@link post} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-postWithToken */ postWithToken( @@ -319,7 +343,7 @@ declare global { * Post to API with csrf token. If we have no token, get one and try to post. If we have a cached token try using that, and if it fails, blank out the cached token and start over. * * @param {UnknownApiParams} params API parameters - * @param {JQuery.AjaxSettings} [ajaxOptions] + * @param {JQuery.AjaxSettings} [ajaxOptions] See {@link post} * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.edit-method-postWithEditToken */ @@ -419,7 +443,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} + * @returns {JQuery.Promise} Edit API response * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.edit-method-edit */ edit( @@ -483,7 +507,7 @@ declare global { saveOption(name: string, value: string | null): JQuery.Promise; /** - * Asynchronously save the values of user options using the API. + * Asynchronously save the values of user options using the [Options API](https://www.mediawiki.org/wiki/API:Options). * * If a value of `null` is provided, the given option will be reset to the default value. * @@ -541,7 +565,7 @@ declare global { * @since 1.27 * @param {string|string[]} messages Messages to retrieve * @param {ApiQueryAllMessagesParams} [options] Additional parameters for the API call - * @returns {JQuery.Promise>>} + * @returns {JQuery.Promise>} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.messages-method-getMessages */ getMessages( @@ -711,7 +735,7 @@ declare global { /** * @param {string} username * @param {string} password - * @returns {JQuery.Promise} + * @returns {JQuery.Promise} See {@link post()} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.login-method-login */ login(username: string, password: string): JQuery.Promise; diff --git a/mw/Rest.d.ts b/mw/Rest.d.ts index 483c0f5..d412830 100644 --- a/mw/Rest.d.ts +++ b/mw/Rest.d.ts @@ -120,7 +120,7 @@ declare global { * * @param {string} path * @param {JQuery.AjaxSettings} [ajaxOptions] - * @returns {JQuery.Promise} API response data and the jqXHR object + * @returns {JQuery.Promise} Done: API response data and the jqXHR object. * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-ajax */ ajax(path: string, ajaxOptions?: JQuery.AjaxSettings): JQuery.Promise; diff --git a/mw/experiments.d.ts b/mw/experiments.d.ts index 06e4ca6..2d09da8 100644 --- a/mw/experiments.d.ts +++ b/mw/experiments.d.ts @@ -25,6 +25,7 @@ declare global { * The name of the experiment and the token are hashed. The hash is converted * to a number which is then used to get a bucket. * + * @example * ```js * // The experiment has three buckets: control, A, and B. The user has a 50% chance of * // being assigned to the control bucket, and a 25% chance of being assigned to either diff --git a/mw/html.d.ts b/mw/html.d.ts index 30b8d49..2ec8b5c 100644 --- a/mw/html.d.ts +++ b/mw/html.d.ts @@ -3,6 +3,7 @@ declare global { /** * HTML construction helper functions * + * @example * ```js * var Html, output; * diff --git a/mw/language.d.ts b/mw/language.d.ts index fba935e..26784c6 100644 --- a/mw/language.d.ts +++ b/mw/language.d.ts @@ -48,36 +48,6 @@ declare global { */ const data: Record; - /** - * Information about month names in current UI language. - * - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-property-months - */ - const months: { - /** - * Array of month names (in nominative case in languages which have the distinction), - * zero-indexed. - */ - abbrev: string[]; - - /** - * Object containing zero-indexed arrays of message keys for appropriate messages - * which can be passed to {@link mw.msg}. - */ - keys: Record<"abbrev" | "genitive" | "names", string[]>; - - /** - * Array of month names in genitive case, zero-indexed. - */ - genitive: string[]; - - /** - * Array of month names (in nominative case in languages which have the distinction), - * zero-indexed. - */ - names: string[]; - }; - /** * Formats language tags according the BCP 47 standard. * See LanguageCode::bcp47 for the PHP implementation. @@ -228,6 +198,36 @@ declare global { forms: T, count: number ): [...T, ...string[]]; + + /** + * Information about month names in current UI language. + * + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-property-months + */ + namespace months { + /** + * Array of month names (in nominative case in languages which have the distinction), + * zero-indexed. + */ + const abbrev: string[]; + + /** + * Object containing zero-indexed arrays of message keys for appropriate messages + * which can be passed to {@link mw.msg}. + */ + const keys: Record<"abbrev" | "genitive" | "names", string[]>; + + /** + * Array of month names in genitive case, zero-indexed. + */ + const genitive: string[]; + + /** + * Array of month names (in nominative case in languages which have the distinction), + * zero-indexed. + */ + const names: string[]; + } } } } diff --git a/mw/loader.d.ts b/mw/loader.d.ts index 5b155f2..177c2ff 100644 --- a/mw/loader.d.ts +++ b/mw/loader.d.ts @@ -433,6 +433,7 @@ declare global { * @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 */ + // note: U is required so T is not inferred from the "modules" argument function resolve(modules: U[]): T[]; /** diff --git a/mw/log.d.ts b/mw/log.d.ts index 841bc75..3fc05a0 100644 --- a/mw/log.d.ts +++ b/mw/log.d.ts @@ -9,7 +9,6 @@ declare global { * @param {string} [topic='error.caught'] Error topic. Conventionally in the form * 'error.?component?' (where ?component? identifies the code logging the error at a * high level; e.g. an extension name). - * @fires error_caught * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.log */ function logError(error: Error, topic?: `error.${string}`): void; diff --git a/mw/message.d.ts b/mw/message.d.ts index b37dfc0..0ef9735 100644 --- a/mw/message.d.ts +++ b/mw/message.d.ts @@ -24,6 +24,7 @@ declare global { * * Similar to the Message class in MediaWiki PHP. * + * @example * ```js * var obj, str; * mw.messages.set( { @@ -68,6 +69,7 @@ declare global { * * Similar to the Message class in MediaWiki PHP. * + * @example * ```js * var obj, str; * mw.messages.set( { diff --git a/mw/util.d.ts b/mw/util.d.ts index 922377e..9507829 100644 --- a/mw/util.d.ts +++ b/mw/util.d.ts @@ -163,7 +163,6 @@ declare global { * @param {HTMLElement|JQuery|string} [nextnode] Element that the new item should be added before. * Must be another item in the same list, it will be ignored otherwise. * Can be specified as DOM reference, as jQuery object, or as CSS selector string. - * @fires util_addPortletLink * @returns {HTMLLIElement|null} The added list item, or null if no element was added. * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.util-method-addPortletLink */ diff --git a/tslint.json b/tslint.json index 2ace968..9e69060 100644 --- a/tslint.json +++ b/tslint.json @@ -2,7 +2,6 @@ "extends": ["dtslint/dtslint.json", "tslint-config-prettier"], "rules": { "no-padding": false, - "no-unnecessary-qualifier": false, "unified-signatures": false, "no-redundant-jsdoc": false, "no-unnecessary-generics": false