diff --git a/README.md b/README.md index e429444..f059ec8 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Edit your project's `tsconfig.json` file so that it includes ] ``` -You should be all set! `mw` will be available in the global scope. There is no need to put any import statements in the TypeScript source files. +You should be all set! `mw` will be available in the global scope. There is no need to put any import statements in the TypeScript source files. **If you find any errors or have suggestions for more specific typings, please open a PR or file an issue.** @@ -58,4 +58,3 @@ import type { ApiEditPageParams, ApiParseParams } from "types-mediawiki/api_para ``` Since it is just a type import, it doesn't generate any JavaScript. Hence, such imports can also be used in non-modular applications. - diff --git a/jquery/client.d.ts b/jquery/client.d.ts index 0b82e40..774d2b2 100644 --- a/jquery/client.d.ts +++ b/jquery/client.d.ts @@ -1,5 +1,8 @@ declare global { interface JQueryStatic { + /** + * User-agent detection + */ client: Client; } } @@ -10,26 +13,30 @@ interface Client { * * The resulting client object will be in the following format: * - * { - * 'name': 'firefox', - * 'layout': 'gecko', - * 'layoutVersion': 20101026, - * 'platform': 'linux' - * 'version': '3.5.1', - * 'versionBase': '3', - * 'versionNumber': 3.5, - * } + * ```js + * { + * 'name': 'firefox', + * 'layout': 'gecko', + * 'layoutVersion': 20101026, + * 'platform': 'linux' + * 'version': '3.5.1', + * 'versionBase': '3', + * 'versionNumber': 3.5, + * } + * ``` * * Example: * - * if ( $.client.profile().layout == 'gecko' ) { - * // This will only run in Gecko browsers, such as Mozilla Firefox. - * } + * ```js + * if ( $.client.profile().layout == 'gecko' ) { + * // This will only run in Gecko browsers, such as Mozilla Firefox. + * } * - * var profile = $.client.profile(); - * if ( profile.layout == 'gecko' && profile.platform == 'linux' ) { - * // This will only run in Gecko browsers on Linux. - * } + * var profile = $.client.profile(); + * if ( profile.layout == 'gecko' && profile.platform == 'linux' ) { + * // This will only run in Gecko browsers on Linux. + * } + * ``` * * Recognised browser names: * @@ -82,34 +89,37 @@ interface Client { * * A browser map is in the following format: * - * { - * // Multiple rules with configurable operators - * 'msie': [['>=', 7], ['!=', 9]], - * // Match no versions - * 'iphone': false, - * // Match any version - * 'android': null - * } + * ```js + * { + * // Multiple rules with configurable operators + * 'msie': [['>=', 7], ['!=', 9]], + * // Match no versions + * 'iphone': false, + * // Match any version + * 'android': null + * } + * ``` * * It can optionally be split into ltr/rtl sections: * - * { - * 'ltr': { - * 'android': null, - * 'iphone': false - * }, - * 'rtl': { - * 'android': false, - * // rules are not inherited from ltr - * 'iphone': false - * } + * ```js + * { + * 'ltr': { + * 'android': null, + * 'iphone': false + * }, + * 'rtl': { + * 'android': false, + * // rules are not inherited from ltr + * 'iphone': false * } + * } + * ``` * * @param {Object} map Browser support map * @param {Object} [profile] A client-profile object * @param {boolean} [exactMatchOnly=false] Only return true if the browser is matched, * otherwise returns true if the browser is not found. - * * @return {boolean} The current browser is in the support map */ test(map: any, profile?: ClientProfile, exactMatchOnly?: boolean): boolean; diff --git a/jquery/collapsibleTabs.d.ts b/jquery/collapsibleTabs.d.ts index accb571..b218fdf 100644 --- a/jquery/collapsibleTabs.d.ts +++ b/jquery/collapsibleTabs.d.ts @@ -13,13 +13,21 @@ declare global { } } -/** A jQuery plugin that makes collapsible tabs for the Vector skin. */ +/** + * A jQuery plugin that makes collapsible tabs for the Vector skin. + */ interface CollapsibleTabsOptions { - /** Optional tab selector. Defaults to `#p-views ul`. */ + /** + * Optional tab selector. Defaults to `#p-views ul`. + */ expandedContainer: string; - /** Optional menu item selector. Defaults to `#p-cactions ul`. */ + /** + * Optional menu item selector. Defaults to `#p-cactions ul`. + */ collapsedContainer: string; - /** Optional selector for tabs that are collapsible. Defaults to `li.collapsible`. */ + /** + * Optional selector for tabs that are collapsible. Defaults to `li.collapsible`. + */ collapsible: string; shifting: boolean; expandedWidth: number; diff --git a/jquery/colorUtil.d.ts b/jquery/colorUtil.d.ts index 3332e89..1f7d2e0 100644 --- a/jquery/colorUtil.d.ts +++ b/jquery/colorUtil.d.ts @@ -67,10 +67,12 @@ interface ColorUtil { * * Usage: * - * $.colorUtil.getColorBrightness( 'red', +0.1 ); - * // > "rgb(255,50,50)" - * $.colorUtil.getColorBrightness( 'rgb(200,50,50)', -0.2 ); - * // > "rgb(118,29,29)" + * ```js + * $.colorUtil.getColorBrightness( 'red', +0.1 ); + * // > "rgb(255,50,50)" + * $.colorUtil.getColorBrightness( 'rgb(200,50,50)', -0.2 ); + * // > "rgb(118,29,29)" + * ``` * * @param {Mixed} currentColor Current value in css * @param {number} mod Wanted brightness modification between -1 and 1 diff --git a/jquery/index.d.ts b/jquery/index.d.ts index cf11390..14b9c18 100644 --- a/jquery/index.d.ts +++ b/jquery/index.d.ts @@ -1,6 +1,6 @@ import "jquery"; -import "./textSelection"; -import "./collapsibleTabs"; import "./client"; +import "./collapsibleTabs"; import "./colorUtil"; +import "./textSelection"; diff --git a/jquery/textSelection.d.ts b/jquery/textSelection.d.ts index 0a85786..903257a 100644 --- a/jquery/textSelection.d.ts +++ b/jquery/textSelection.d.ts @@ -1,17 +1,55 @@ declare global { interface JQuery { - // one overload for each command + /** + * Get the contents of the textarea. + * + * @param {string} command Command to execute + * @return {string} + */ textSelection(command: "getContents"): string; + /** + * Set the contents of the textarea, replacing anything that was there before. + * + * @param {string} command Command to execute + * @param {string} content + * @return {JQuery} + * @chainable + */ textSelection(command: "setContents"): JQuery; + /** + * Get the currently selected text in this textarea. + * + * @param {string} command Command to execute + * @return {string} + */ textSelection(command: "getSelection"): string; + /** + * Replace the selected text in the textarea with the given text, or insert it at the cursor. + * + * @param {string} command Command to execute + * @param {string} value + * @return {JQuery} + * @chainable + */ textSelection(command: "replaceSelection"): JQuery; + /** + * Insert text at the beginning and end of a text selection, optionally + * inserting text at the caret when selection is empty. + * + * Also focusses the textarea. + * + * @param {string} command Command to execute + * @param {Object} [options] + * @return {JQuery} + * @chainable + */ textSelection( command: "encapsulateSelection", - commandOptions: { + options: { pre?: string; peri?: string; post?: string; @@ -24,38 +62,73 @@ declare global { } ): JQuery; + /** + * Get the current cursor position (in UTF-16 code units) in a textarea. + * + * @param {string} command Command to execute + * @param {Object} [options] + * @param {Object} [options.startAndEnd=false] Return range of the selection rather than just start + * @return {Array} Array with two numbers, for start and end of selection + */ textSelection( command: "getCaretPosition", - commandOptions?: { - startAndEnd?: false; - } - ): number; - - textSelection( - command: "getCaretPosition", - commandOptions: { - startAndEnd: true; - } + options: { startAndEnd: true } ): [number, number]; - textSelection( - command: "setSelection", - commandOptions: { - start?: number; - end?: number; - } - ): JQuery; + /** + * Get the current cursor position (in UTF-16 code units) in a textarea. + * + * @param {string} command Command to execute + * @param {Object} [options] + * @param {Object} [options.startAndEnd=false] Return range of the selection rather than just start + * @return {number} + */ + textSelection(command: "getCaretPosition", options?: { startAndEnd?: false }): number; + + /** + * Set the current cursor position (in UTF-16 code units) in a textarea. + * + * @param {string} command Command to execute + * @param {Object} options + * @param {number} options.start + * @param {number} [options.end=options.start] + * @return {JQuery} + * @chainable + */ + textSelection(command: "setSelection", options: { start?: number; end?: number }): JQuery; + + /** + * Scroll a textarea to the current cursor position. You can set the cursor + * position with 'setSelection'. + * + * @param {string} command Command to execute + * @param {Object} [options] + * @param {string} [options.force=false] Whether to force a scroll even if the caret position + * is already visible. + * @return {JQuery} + * @chainable + */ + textSelection(command: "scrollToCaretPosition", options: { force?: boolean }): JQuery; + /** + * Register an alternative textSelection API for this element. + * + * @param {string} command Command to execute + * @param {Object} functions Functions to replace. Keys are command names (as in {@link textSelection}, + * except 'register' and 'unregister'). Values are functions to execute when a given command is + * called. + */ textSelection( - command: "scrollToCaretPosition", - commandOptions: { - force?: boolean; - } - ): JQuery; + command: "register", + functions: Record any> + ): void; + /** + * Unregister the alternative textSelection API for this element (see 'register'). + * + * @param {string} command Command to execute + */ textSelection(command: "unregister"): void; - - textSelection(command: "register", commandOptions: Record any>): void; } } diff --git a/mw/Api.d.ts b/mw/Api.d.ts index 4665ba8..086e0d1 100644 --- a/mw/Api.d.ts +++ b/mw/Api.d.ts @@ -12,7 +12,7 @@ type ApiParams = Record type ApiResponse = Record; // it will always be a JSON object, the rest is uncertain ... /** - * Default options for jQuery#ajax calls. Can be overridden by passing + * Default options for {@link jQuery.ajax} calls. Can be overridden by passing * `options` to {@link mw.Api} constructor. * * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-property-defaultOptions @@ -23,7 +23,7 @@ export interface ApiOptions { */ parameters?: ApiParams; /** - * Default options for jQuery#ajax + * Default options for {@link jQuery.ajax} */ ajax?: JQuery.AjaxSettings; /** @@ -41,6 +41,7 @@ declare global { class Api { /** * Constructor to create an object to interact with the API of a particular MediaWiki server. mw.Api objects represent the API of a particular MediaWiki server. + * * ```js * var api = new mw.Api(); * api.get( { @@ -50,7 +51,9 @@ declare global { * console.log( data ); * } ); * ``` + * * Since MW 1.25, multiple values for a parameter can be specified using an array: + * * ```js * var api = new mw.Api(); * api.get( { @@ -60,9 +63,10 @@ declare global { * console.log( data ); * } ); * ``` + * * Since MW 1.26, boolean values for a parameter can be specified directly. If the value is false or undefined, the parameter will be omitted from the request, as required by the API. * - * @param {ApiOptions} options + * @param {ApiOptions} [options] * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-constructor */ constructor(options?: ApiOptions); @@ -84,7 +88,7 @@ declare global { * Perform API get request. * * @param {ApiParams} parameters - * @param {JQuery.AjaxSettings?} ajaxOptions + * @param {JQuery.AjaxSettings} [ajaxOptions] * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-get */ @@ -97,7 +101,7 @@ declare global { * Perform API post request. * * @param {ApiParams} parameters - * @param {JQuery.AjaxSettings?} ajaxOptions + * @param {JQuery.AjaxSettings} [ajaxOptions] * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-post */ @@ -120,7 +124,7 @@ declare global { * Perform the API call. * * @param {ApiParams} parameters - * @param {JQuery.AjaxSettings?} ajaxOptions + * @param {JQuery.AjaxSettings} [ajaxOptions] * @returns {JQuery.Promise} API response data and the jqXHR object * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-ajax */ @@ -133,6 +137,7 @@ declare global { * 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: + * * ```js * new mw.Api().postWithToken( 'csrf', { * action: 'options', @@ -143,7 +148,7 @@ declare global { * * @param {string} tokenType The name of the token, like `options` or `edit` * @param {ApiParams} params API parameters - * @param {JQuery.AjaxSettings?} ajaxOptions + * @param {JQuery.AjaxSettings} [ajaxOptions] * @returns {JQuery.Promise} * @since 1.22 * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-postWithToken @@ -158,7 +163,7 @@ declare global { * Get a token for a certain action from the API. * * @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) + * @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 @@ -221,7 +226,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 {APIParams} params API parameters - * @param {JQuery.AjaxSettings?} ajaxOptions + * @param {JQuery.AjaxSettings} [ajaxOptions] * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.edit-method-postWithEditToken */ @@ -233,7 +238,7 @@ declare global { /** * API helper to grab a csrf token. * - * @returns {JQuery.Promise} + * @returns {JQuery.Promise} Received token. * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.edit-method-getEditToken */ getEditToken(): JQuery.Promise; @@ -242,6 +247,7 @@ declare global { * Create a new page. * * Example: + * * ```js * new mw.Api().create( 'Sandbox', * { summary: 'Load sand particles.' }, @@ -252,7 +258,7 @@ declare global { * @param {TitleLike} title Page title * @param {ApiEditPageParams} params Edit API parameters * @param {string} content Page content - * @returns {} + * @returns {JQuery.Promise} API response * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.edit-method-create */ create( @@ -267,6 +273,7 @@ declare global { * To create a new page, use create() instead. * * Simple transformation: + * * ```js * new mw.Api() * .edit( 'Sandbox', function ( revision ) { @@ -276,7 +283,9 @@ declare global { * console.log( 'Saved!' ); * } ); * ``` + * * Set save parameters by returning an object instead of a string: + * * ```js * new mw.Api().edit( * 'Sandbox', @@ -293,7 +302,9 @@ declare global { * console.log( 'Saved!' ); * } ); * ``` + * * Transform asynchronously by returning a promise. + * * ```js * new mw.Api() * .edit( 'Sandbox', function ( revision ) { @@ -394,7 +405,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 + * @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 */ @@ -404,7 +415,7 @@ declare global { * Convenience method for `action=watch`. * * @param {TitleLike | TitleLikeArray} pages - * @param {string?} expiry + * @param {string} [expiry] * @returns {JQuery.Promise<{ watch: { title: string, watched: boolean } | Array<{ title: string, watched: boolean }> }>} * @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 @@ -436,21 +447,19 @@ declare global { /** * Convenience method for `action=parse`. * - * @param {string | mw.Title} content Content to parse, either as a wikitext string or a mw.Title - * @param {ApiParseParams} additionalParams - * @returns {JQuery.Promise} + * @param {TitleLike} content Content to parse, either as a wikitext string or a mw.Title + * @param {ApiParseParams} [additionalParams] Parameters object to set custom settings, e.g. + * redirects, sectionpreview. prop should not be overridden. + * @returns {JQuery.Promise} Parsed HTML of `wikitext`. * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.parse-method-parse */ - parse( - content: string | mw.Title, - additionalParams?: ApiParseParams - ): JQuery.Promise; + parse(content: TitleLike, additionalParams?: ApiParseParams): JQuery.Promise; /** * Get a set of messages. * * @param {string[]} messages Messages to retrieve - * @param {ApiQueryAllMessagesParams?} options Additional parameters for the API call + * @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 */ @@ -463,7 +472,7 @@ declare global { * Load a set of messages and add them to `mw.messages`. * * @param {string[]} messages Messages to retrieve - * @param {ApiQueryAllMessagesParams?} options Additional parameters for the API call + * @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 */ @@ -476,7 +485,7 @@ declare global { * 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. * * @param {string[]} messages Messages to retrieve - * @param {ApiQueryAllMessagesParams?} options Additional parameters for the API call + * @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-loadMessagesIfMissing */ @@ -519,7 +528,8 @@ declare global { * * @param {TitleLike} page * @param {string} user - * @param {ApiRollbackParams?} params Additional parameters + * @param {ApiRollbackParams} [params] Additional parameters + * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.rollback-method-rollback */ rollback( @@ -533,8 +543,8 @@ declare global { * * @param {File} file * @param {ApiUploadParams} data Other upload options, see `action=upload` API docs for more - * @param {number?} chunkSize Size (in bytes) per chunk (default: 5MB) - * @param {number?} chunkRetries Amount of times to retry a failed chunk (default: 1) + * @param {number} [chunkSize] Size (in bytes) per chunk (default: 5MB) + * @param {number} [chunkRetries] Amount of times to retry a failed chunk (default: 1) * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.upload-method-chunkedUpload */ @@ -551,9 +561,9 @@ declare global { * This function will return a promise that will resolve with a function to finish the stash upload. * * @param {File | HTMLInputElement} file - * @param {ApiUploadParams?} data - * @param {number?} chunkSize Size (in bytes) per chunk (default: 5MB) - * @param {number?} chunkRetries Amount of times to retry a failed chunk (default: 1) + * @param {ApiUploadParams} [data] + * @param {number} [chunkSize] Size (in bytes) per chunk (default: 5MB) + * @param {number} [chunkRetries] Amount of times to retry a failed chunk (default: 1) * @returns {JQuery.Promise<(data?: ApiUploadParams) => JQuery.Promise>} Call this function to finish the upload * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.upload-method-chunkedUploadToStash */ @@ -593,6 +603,7 @@ declare global { * Upload a file to the stash. * * This function will return a promise that will resolve with a function to finish the stash upload. You can call that function with an argument containing more, or conflicting, data to pass to the server. For example: + * * ```js * // upload a file to the stash with a placeholder filename * api.uploadToStash( file, { filename: 'testing.png' } ).done( function ( finish ) { @@ -605,7 +616,7 @@ declare global { * ``` * * @param {File | HTMLInputElement} file - * @param {ApiUploadParams?} data + * @param {ApiUploadParams} [data] * @return {JQuery.Promise} * @returns {JQuery.Promise<(data?: ApiUploadParams) => JQuery.Promise>} Call this function to finish the upload * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.upload-method-uploadToStash diff --git a/mw/ForeignApi.d.ts b/mw/ForeignApi.d.ts index 4959efe..321c5d6 100644 --- a/mw/ForeignApi.d.ts +++ b/mw/ForeignApi.d.ts @@ -12,11 +12,12 @@ declare global { /** * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignApi */ - class ForeignApi extends mw.Api { + class ForeignApi extends Api { /** - * Create an object like `mw.Api`, but automatically handling everything required to communicate with another MediaWiki wiki via cross-origin requests (CORS). + * Create an object like {@link mw.Api}, but automatically handling 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 for details. + * * ```js * var api = new mw.ForeignApi( 'https://commons.wikimedia.org/w/api.php' ); * api.get( { @@ -30,18 +31,19 @@ declare global { * To ensure that the user at the foreign wiki is logged in, pass the `assert: 'user'` parameter to `get()`/`post()` (since MW 1.23): if they are not, the API request will fail. (Note that this doesn't guarantee that it's the same user.) * * 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; * ``` * - * @param {string | mw.Uri} url URL pointing to another wiki's `api.php` endpoint. - * @param {ForeignApiOptions?} options + * @param {string | Uri} url URL pointing to another wiki's `api.php` endpoint. + * @param {ForeignApiOptions} [options] * @since 1.26 * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignApi-method-constructor */ - constructor(url: string | mw.Uri, options?: ForeignApiOptions); + constructor(url: string | Uri, options?: ForeignApiOptions); /** * Return the origin to use for API requests, in the required format (protocol, host and port, if any). diff --git a/mw/ForeignRest.d.ts b/mw/ForeignRest.d.ts index 631fd66..d1624af 100644 --- a/mw/ForeignRest.d.ts +++ b/mw/ForeignRest.d.ts @@ -14,9 +14,9 @@ declare global { /** * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignRest */ - class ForeignRest extends mw.Rest { + class ForeignRest extends Rest { /** - * Create an object like `mw.Rest`, but automatically handling everything required + * Create an object like {@link mw.Rest}, but automatically handling 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 https://www.mediawiki.org/wiki/Manual:$wgCrossSiteAJAXdomains for details. @@ -41,15 +41,15 @@ declare global { * mw.ForeignRest = MyForeignRest; * ``` * - * @param {string | mw.Uri} url URL pointing to another wiki's rest.php endpoint. - * @param {mw.ForeignApi} foreignActionApi - * @param {ForeignRestOptions?} options + * @param {string | Uri} url URL pointing to another wiki's rest.php endpoint. + * @param {ForeignApi} foreignActionApi + * @param {ForeignRestOptions} [options] * @since 1.26 * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignApi-method-constructor */ constructor( - url: string | mw.Uri, - foreignActionApi: mw.ForeignApi, + url: string | Uri, + foreignActionApi: ForeignApi, options?: ForeignRestOptions ); } diff --git a/mw/Map.d.ts b/mw/Map.d.ts index 6d42de8..790067e 100644 --- a/mw/Map.d.ts +++ b/mw/Map.d.ts @@ -6,6 +6,7 @@ declare global { * * **NOTE**: This is a private utility class for internal use by the framework. * Don't rely on its existence. + * * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Map */ class Map = any> { @@ -15,6 +16,7 @@ declare global { * Get the value of one or more keys. * * If called with no arguments, all values are returned. + * * @param selection Key or array of keys to retrieve values for. * @param fallback Value for keys that don't exist. * @returns If selection was a string, returns the value. If selection was an array, returns @@ -41,6 +43,7 @@ declare global { /** * Check if a given key exists in the map. + * * @param selection Key to check * @returns True if the key exists * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Map-method-exists diff --git a/mw/RegExp.d.ts b/mw/RegExp.d.ts index 238a077..5518e1a 100644 --- a/mw/RegExp.d.ts +++ b/mw/RegExp.d.ts @@ -1,7 +1,6 @@ declare global { namespace mw { /** - * @class mw.RegExp * @see https://doc.wikimedia.org/mediawiki-core/REL1_29/js/source/mediawiki.RegExp.html */ namespace RegExp { diff --git a/mw/Rest.d.ts b/mw/Rest.d.ts index f2b1021..db1b8d5 100644 --- a/mw/Rest.d.ts +++ b/mw/Rest.d.ts @@ -1,11 +1,3 @@ -import { - ApiEditPageParams, - ApiParseParams, - ApiQueryAllMessagesParams, - ApiRollbackParams, - ApiUploadParams, -} from "../api_params"; - export interface RestOptions { ajax: JQuery.AjaxSettings; } @@ -43,7 +35,7 @@ declare global { * } ); * ``` * - * @param {RestOptions} options + * @param {RestOptions} [options] * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Rest-method-constructor */ constructor(options?: RestOptions); @@ -131,7 +123,7 @@ declare global { * Perform the API call. * * @param {string} path - * @param {JQuery.AjaxSettings?} ajaxOptions + * @param {JQuery.AjaxSettings} [ajaxOptions] * @returns {JQuery.Promise} API response data and the jqXHR object * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-ajax */ diff --git a/mw/Title.d.ts b/mw/Title.d.ts index 8130a37..28efe24 100644 --- a/mw/Title.d.ts +++ b/mw/Title.d.ts @@ -4,54 +4,62 @@ declare global { namespace mw { /** * Parse titles into an object structure. Note that when using the constructor - * directly, passing invalid titles will result in an exception. Use #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. * - * Note that in the constructor and #newFromText method, `namespace` is the **default** namespace + * Note that in the constructor and {@link newFromText} method, `namespace` is the **default** namespace * only, and can be overridden by a namespace prefix in `title`. If you do not want this behavior, - * use #makeTitle. Compare: + * use {@link makeTitle}. Compare: * - * new mw.Title( 'Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo' - * mw.Title.newFromText( 'Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo' - * mw.Title.makeTitle( NS_TEMPLATE, 'Foo' ).getPrefixedText(); // => 'Template:Foo' + * ```js + * new mw.Title( 'Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo' + * mw.Title.newFromText( 'Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo' + * mw.Title.makeTitle( NS_TEMPLATE, 'Foo' ).getPrefixedText(); // => 'Template:Foo' * - * new mw.Title( 'Category:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Category:Foo' - * mw.Title.newFromText( 'Category:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Category:Foo' - * mw.Title.makeTitle( NS_TEMPLATE, 'Category:Foo' ).getPrefixedText(); // => 'Template:Category:Foo' + * new mw.Title( 'Category:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Category:Foo' + * mw.Title.newFromText( 'Category:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Category:Foo' + * mw.Title.makeTitle( NS_TEMPLATE, 'Category:Foo' ).getPrefixedText(); // => 'Template:Category:Foo' * - * new mw.Title( 'Template:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo' - * mw.Title.newFromText( 'Template:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo' - * mw.Title.makeTitle( NS_TEMPLATE, 'Template:Foo' ).getPrefixedText(); // => 'Template:Template:Foo' + * new mw.Title( 'Template:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo' + * mw.Title.newFromText( 'Template:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo' + * mw.Title.makeTitle( NS_TEMPLATE, 'Template:Foo' ).getPrefixedText(); // => 'Template:Template:Foo' + * ``` * - * @class mw.Title * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title */ class Title { /** * Store page existence * - * @static * @property {Object} exist - * @property {Object} exist.pages Keyed by title. Boolean true value indicates page does exist. - * - * @property {Function} exist.set The setter function. - * - * Example to declare existing titles: - * - * Title.exist.set( ['User:John_Doe', ...] ); - * - * Example to declare titles nonexistent: - * - * Title.exist.set( ['File:Foo_bar.jpg', ...], false ); - * - * @property {string|Array} exist.set.titles Title(s) in strict prefixedDb title form - * @property {boolean} [exist.set.state=true] State of the given titles - * @return {boolean} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-static-property-exist */ static exist: { + /** + * Keyed by title. Boolean true value indicates page does exist. + */ pages: { [title: string]: boolean }; - set: (titles: string | string[], state?: boolean) => boolean; + + /** + * The setter function. + * + * Example to declare existing titles: + * + * ```js + * Title.exist.set( ['User:John_Doe', ...] ); + * ``` + * + * Example to declare titles nonexistent: + * + * ```js + * Title.exist.set( ['File:Foo_bar.jpg', ...], false ); + * ``` + * + * @param {string|Array} titles Title(s) in strict prefixedDb title form + * @param {boolean} [state=true] State of the given titles + * @return {boolean} + */ + set(titles: string | string[], state?: boolean): boolean; }; /** @@ -94,7 +102,7 @@ declare global { * "File:Example_image.svg" will be returned as "Example image". * * Note that this method will work for non-file titles but probably give nonsensical results. - * A title like "User:Dr._J._Fail" will be returned as "Dr. J"! Use #getMainText instead. + * A title like "User:Dr._J._Fail" will be returned as "Dr. J"! Use {@link getMainText} instead. * * @return {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getFileNameTextWithoutExtension @@ -107,7 +115,7 @@ declare global { * "File:Example_image.svg" will be returned as "Example_image". * * Note that this method will work for non-file titles but probably give nonsensical results. - * A title like "User:Dr._J._Fail" will be returned as "Dr._J"! Use #getMain instead. + * A title like "User:Dr._J._Fail" will be returned as "Dr._J"! Use {@link getMain} instead. * * @return {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getFileNameWithoutExtension @@ -145,6 +153,19 @@ declare global { */ getMainText(): string; + /** + * Get the page name as if it is a file name, without extension or namespace prefix. Warning, + * this is usually not what you want! A title like "User:Dr._J._Fail" will be returned as + * "Dr. J"! Use {@link getMain} or {@link getMainText} for the actual page name. + * + * @deprecated since 1.40, use {@link getFileNameWithoutExtension} instead + * @return {string} File name without file extension, in the canonical form with underscores + * instead of spaces. For example, the title "File:Example_image.svg" will be returned as + * "Example_image". + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getName + */ + getName(): string; + /** * Get the namespace number * @@ -166,6 +187,19 @@ declare global { */ getNamespacePrefix(): string; + /** + * Get the page name as if it is a file name, without extension or namespace prefix. Warning, + * this is usually not what you want! A title like "User:Dr._J._Fail" will be returned as + * "Dr. J"! Use {@link getMainText} for the actual page name. + * + * @deprecated since 1.40, use {@link getFileNameTextWithoutExtension} instead + * @return {string} File name without file extension, formatted with spaces instead of + * underscores. For example, the title "File:Example_image.svg" will be returned as + * "Example image". + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getNameText + */ + getNameText(): string; + /** * Get the full page name * @@ -205,7 +239,7 @@ declare global { /** * Get the title for the subject page of a talk page * - * @return {mw.Title|null} The title for the subject page of a talk page, null if not available + * @return {Title|null} The title for the subject page of a talk page, null if not available * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getSubjectPage */ getSubjectPage(): Title | null; @@ -213,7 +247,7 @@ declare global { /** * Get the title for the associated talk page * - * @return {mw.Title|null} The title for the associated talk page, null if not available + * @return {Title|null} The title for the associated talk page, null if not available * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getTalkPage */ getTalkPage(): Title | null; @@ -228,17 +262,6 @@ declare global { */ getUrl(params?: any): string; - /** - * Check if a given namespace is a talk namespace - * - * See NamespaceInfo::isTalk in PHP - * - * @param {number} namespaceId Namespace ID - * @return {boolean} Namespace is a talk namespace - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-isTalkNamespace - */ - isTalkNamespace(namespaceId: number): boolean; - /** * Check if the title is in a talk namespace * @@ -248,27 +271,7 @@ declare global { isTalkPage(): boolean; /** - * Normalize a file extension to the common form, making it lowercase and checking some synonyms, - * and ensure it's clean. Extensions with non-alphanumeric characters will be discarded. - * Keep in sync with File::normalizeExtension() in PHP. - * - * @param {string} extension File extension (without the leading dot) - * @return {string} File extension in canonical form - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-normalizeExtension - */ - normalizeExtension(extension: string): string; - - /** - * PHP's strtoupper differs from String.toUpperCase in a number of cases (T147646). - * - * @param {string} chr Unicode character - * @return {string} Unicode character, in upper case, according to the same rules as in PHP - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-phpCharToUpper - */ - phpCharToUpper(chr: string): string; - - /** - * Alias of mw.Title#getPrefixedDb + * Alias of {@link mw.Title.getPrefixedDb} * * TODO: Use @-alias when we switch to JSDoc * @@ -278,7 +281,7 @@ declare global { toString(): string; /** - * Alias of mw.Title#getPrefixedText + * Alias of {@link mw.Title.getPrefixedText} * * TODO: Use @-alias when we switch to JSDoc * @@ -287,64 +290,36 @@ declare global { */ toText(): string; - /** - * Check if signature buttons should be shown in a given namespace - * - * See NamespaceInfo::wantSignatures in PHP - * - * @param {number} namespaceId Namespace ID - * @return {boolean} Namespace is a signature namespace - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-wantSignaturesNamespace - */ - wantSignatureNamespace(namespaceId: number): boolean; - - /** - * Get the page name as if it is a file name, without extension or namespace prefix. Warning, - * this is usually not what you want! A title like "User:Dr._J._Fail" will be returned as - * "Dr. J"! Use #getMain or #getMainText for the actual page name. - * - * @deprecated since 1.40, use #getFileNameWithoutExtension instead - * @return {string} File name without file extension, in the canonical form with underscores - * instead of spaces. For example, the title "File:Example_image.svg" will be returned as - * "Example_image". - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getName - */ - getName(): string; - - /** - * Get the page name as if it is a file name, without extension or namespace prefix. Warning, - * this is usually not what you want! A title like "User:Dr._J._Fail" will be returned as - * "Dr. J"! Use #getMainText for the actual page name. - * - * @deprecated since 1.40, use #getFileNameTextWithoutExtension instead - * @return {string} File name without file extension, formatted with spaces instead of - * underscores. For example, the title "File:Example_image.svg" will be returned as - * "Example image". - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getNameText - */ - getNameText(): string; - /** * Whether this title exists on the wiki. * - * @static - * @param {string|mw.Title} title prefixed db-key name (string) or instance of Title + * @param {string|Title} title prefixed db-key name (string) or instance of Title * @return {boolean|null} Boolean if the information is available, otherwise null * @throws {Error} If title is not a string or mw.Title * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-static-method-exists */ static exists(title: title): boolean | null; + /** + * Check if a given namespace is a talk namespace + * + * See NamespaceInfo::isTalk in PHP + * + * @param {number} namespaceId Namespace ID + * @return {boolean} Namespace is a talk namespace + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-isTalkNamespace + */ + static isTalkNamespace(namespaceId: number): boolean; + /** * Constructor for Title objects with predefined namespace. * - * Unlike #newFromText or #constructor, this function doesn't allow the given `namespace` to be - * overridden by a namespace prefix in `title`. See #constructor for details about this behavior. + * Unlike {@link newFromText} or {@link constructor}, this function doesn't allow the given `namespace` to be + * overridden by a namespace prefix in `title`. See {@link constructor} for details about this behavior. * * The single exception to this is when `namespace` is 0, indicating the main namespace. The - * function behaves like #newFromText in that case. + * function behaves like {@link newFromText} in that case. * - * @static * @param {number} namespace Namespace to use for the title * @param {string} title * @return {Title|null} A valid Title object or null if the title is invalid @@ -357,7 +332,6 @@ declare global { * so it is most likely a valid MediaWiki title and file name after processing. * Returns null on fatal errors. * - * @static * @param {string} uncleanName The unclean file name including file extension but * without namespace * @return {Title|null} A valid Title object or null if the title is invalid @@ -368,9 +342,10 @@ declare global { /** * Get the file title from an image element * - * var title = mw.Title.newFromImg( imageNode ); + * ```js + * var title = mw.Title.newFromImg( imageNode ); + * ``` * - * @static * @param {HTMLElement|JQuery} img The image to use as a base * @return {Title|null} The file title or null if unsuccessful * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-static-method-newFromImg @@ -381,10 +356,9 @@ declare global { * Constructor for Title objects with a null return instead of an exception for invalid titles. * * Note that `namespace` is the **default** namespace only, and can be overridden by a namespace - * prefix in `title`. If you do not want this behavior, use #makeTitle. See #constructor for + * prefix in `title`. If you do not want this behavior, use {@link makeTitle}. See {@link constructor} for * details. * - * @static * @param {string} title * @param {number} [namespace=NS_MAIN] Default namespace * @return {Title|null} A valid Title object or null if the title is invalid @@ -396,7 +370,6 @@ declare global { * Constructor for Title objects from user input altering that input to * produce a title that MediaWiki will accept as legal * - * @static * @param {string} title * @param {number} [defaultNamespace=NS_MAIN] * If given, will used as default namespace for the given title. @@ -413,6 +386,37 @@ declare global { defaultNamespace?: number, options?: { forUploading: boolean } ): Title; + + /** + * Normalize a file extension to the common form, making it lowercase and checking some synonyms, + * and ensure it's clean. Extensions with non-alphanumeric characters will be discarded. + * Keep in sync with File::normalizeExtension() in PHP. + * + * @param {string} extension File extension (without the leading dot) + * @return {string} File extension in canonical form + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-normalizeExtension + */ + static normalizeExtension(extension: string): string; + + /** + * PHP's strtoupper differs from {@link String.toUpperCase} in a number of cases (T147646). + * + * @param {string} chr Unicode character + * @return {string} Unicode character, in upper case, according to the same rules as in PHP + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-phpCharToUpper + */ + static phpCharToUpper(chr: string): string; + + /** + * Check if signature buttons should be shown in a given namespace + * + * See NamespaceInfo::wantSignatures in PHP + * + * @param {number} namespaceId Namespace ID + * @return {boolean} Namespace is a signature namespace + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-wantSignaturesNamespace + */ + static wantSignatureNamespace(namespaceId: number): boolean; } } } diff --git a/mw/Uri.d.ts b/mw/Uri.d.ts index f7e3173..c32499f 100644 --- a/mw/Uri.d.ts +++ b/mw/Uri.d.ts @@ -21,6 +21,61 @@ declare global { */ function UriRelative(documentLocation: string | ((...args: any[]) => string)): Uri; + /** + * Library for simple URI parsing and manipulation. + * + * 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 + * use cross-domain proxies for an API, constructing simple URL-based API calls, etc. Parsing here + * is regex-based, so may not work on all URIs, but is good enough for most. + * + * You can modify the properties directly, then use the {@link toString} method to extract the full URI + * string again. Example: + * + * ```js + * var uri = new mw.Uri( 'http://example.com/mysite/mypage.php?quux=2' ); + * + * if ( uri.host == 'example.com' ) { + * uri.host = 'foo.example.com'; + * uri.extend( { bar: 1 } ); + * + * $( 'a#id1' ).attr( 'href', uri ); + * // anchor with id 'id1' now links to http://foo.example.com/mysite/mypage.php?bar=1&quux=2 + * + * $( 'a#id2' ).attr( 'href', uri.clone().extend( { bar: 3, pif: 'paf' } ) ); + * // anchor with id 'id2' now links to http://foo.example.com/mysite/mypage.php?bar=3&quux=2&pif=paf + * } + * ``` + * + * Given a URI like + * `http://usr:pwd@www.example.com:81/dir/dir.2/index.htm?q1=0&&test1&test2=&test3=value+%28escaped%29&r=1&r=2#top` + * the returned object will have the following properties: + * + * ```js + * protocol 'http' + * user 'usr' + * password 'pwd' + * host 'www.example.com' + * port '81' + * path '/dir/dir.2/index.htm' + * query { + * q1: '0', + * test1: null, + * test2: '', + * test3: 'value (escaped)' + * r: ['1', '2'] + * } + * fragment 'top' + * ``` + * + * (N.b., '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 , MIT License. + * + * + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri + */ class Uri { /** * @property {string|undefined} fragment For example `top` @@ -71,7 +126,6 @@ declare global { * so the server-side strips these before delivering to the client. * * @private - * @static * @property {Object} parser * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-static-property-parser */ @@ -84,7 +138,6 @@ declare global { * The order here matches the order of captured matches in the `parser` property regexes. * * @private - * @static * @property {string[]} properties * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-static-property-properties */ @@ -103,8 +156,6 @@ declare global { * Construct a new URI object. Throws error if arguments are illegal/impossible, or * otherwise don't parse. * - * @class mw.Uri - * @constructor * @param {Object|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` * properties. If omitted (or set to `undefined`, `null` or empty string), then an object @@ -231,10 +282,9 @@ declare global { /** * Decode a url encoded value. * - * Reversed #encode. Standard decodeURIComponent, with addition of replacing + * Reversed {@link encode}. Standard decodeURIComponent, with addition of replacing * `+` with a space. * - * @static * @param {string} s String to decode * @return {string} Decoded string * @throws {Error} when the string contains an unknown % sequence @@ -249,7 +299,6 @@ declare global { * compliant with RFC 3986. Similar to rawurlencode from PHP and our JS library * mw.util.rawurlencode, except this also replaces spaces with `+`. * - * @static * @param {string} s String to encode * @return {string} Encoded string for URI * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-static-method-encode diff --git a/mw/config.d.ts b/mw/config.d.ts index 557515d..5351183 100644 --- a/mw/config.d.ts +++ b/mw/config.d.ts @@ -3,14 +3,15 @@ declare global { /** * Map of configuration values. * - * Check out [the complete list of configuration values](https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#mw.config) + * Check out {@link https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#mw.config the complete list of configuration values} * on mediawiki.org. * * If `$wgLegacyJavaScriptGlobals` is true, this Map will add its values to the * global `window` object. + * * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-property-config */ - const config: mw.Map<{ + const config: Map<{ debug: boolean; skin: string; stylepath: string; diff --git a/mw/cookie.d.ts b/mw/cookie.d.ts index 7b98476..847fcdc 100644 --- a/mw/cookie.d.ts +++ b/mw/cookie.d.ts @@ -8,6 +8,38 @@ declare global { * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.cookie */ namespace cookie { + /** + * Get the value of a cookie. + * + * @param {string} key The key for the cookie + * @param {string} [prefix] The prefix of the key. If undefined or null, `$wgCookiePrefix` is used + * @param {*} [defaultValue] A value to return if the cookie does not exist + * @returns {*} If the cookie exists, the value of the cookie, otherwise `defaultValue` + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.cookie-method-get + */ + function get( + key: string, + prefix: string | undefined | null, + defaultValue: D + ): string | D; + function get(key: string, prefix?: string): string; + + /** + * Get the value of a `SameSite` = `None` cookie, using the legacy `ss0-` prefix if needed. + * + * @param {string} key The key for the cookie + * @param {string} [prefix] The prefix of the key. If undefined or null, `$wgCookiePrefix` is used + * @param {*} defaultValue A value to return if the cookie does not exist + * @returns {*} If the cookie exists, the value of the cookie, otherwise `defaultValue` + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.cookie-method-getCrossSite + */ + function getCrossSite( + key: string, + prefix: string | undefined | null, + defaultValue: D + ): string | D; + function getCrossSite(key: string, prefix?: string): string; + /** * Set or delete a cookie. * @@ -19,15 +51,16 @@ declare global { * * @param {string} key * @param {string | null} value Value of cookie. If `value` is `null` then this method will instead remove a cookie by name of `key` - * @param {(Object | Date | number)?} options Options object, or expiry date - * @param {(Date | number | null)?} options.expires The expiry date of the cookie or lifetime in seconds. If `options.expires` is null or 0, then a session cookie is set - * @param {string?} options.prefix The prefix of the key - * @param {string?} options.domain The domain attribute of the cookie - * @param {string?} options.path The path attribute of the cookie - * @param {boolean?} options.secure Whether or not to include the secure attribute (Does **not** use the wgCookieSecure configuration variable) - * @param {string?} options.sameSite The `SameSite` flag of the cookie (case-insensitive; default is to omit the flag, which results in `Lax` on modern browsers). Set to `None` *and* set `secure` to `true` if the cookie needs to be visible on cross-domain requests - * @param {boolean?} options.sameSiteLegacy If true, `SameSite` = `None` cookies will also be sent as non-`SameSite` cookies with an "ss0-" prefix, to work around old browsers interpreting the standard differently + * @param {Object | Date | number} [options] Options object, or expiry date + * @param {Date | number | null} [options.expires] The expiry date of the cookie or lifetime in seconds. If `options.expires` is null or 0, then a session cookie is set + * @param {string} [options.prefix] The prefix of the key + * @param {string} [options.domain] The domain attribute of the cookie + * @param {string} [options.path] The path attribute of the cookie + * @param {boolean} [options.secure] Whether or not to include the secure attribute (Does **not** use the wgCookieSecure configuration variable) + * @param {string} [options.sameSite] The `SameSite` flag of the cookie (case-insensitive; default is to omit the flag, which results in `Lax` on modern browsers). Set to `None` *and* set `secure` to `true` if the cookie needs to be visible on cross-domain requests + * @param {boolean} [options.sameSiteLegacy] If true, `SameSite` = `None` cookies will also be sent as non-`SameSite` cookies with an "ss0-" prefix, to work around old browsers interpreting the standard differently * @returns {void} + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.cookie-method-set */ // see https://stackoverflow.com/a/64932909 for function set( @@ -45,36 +78,6 @@ declare global { sameSite: Lowercase extends SameSite ? SS : SameSite; }> ): void; - - /** - * Get the value of a cookie. - * - * @param {string} key The key for the cookie - * @param {string?} prefix The prefix of the key. If undefined or null, `$wgCookiePrefix` is used - * @param {*} defaultValue A value to return if the cookie does not exist - * @returns {*} If the cookie exists, the value of the cookie, otherwise `defaultValue` - */ - function get( - key: string, - prefix: string | undefined | null, - defaultValue: D - ): string | D; - function get(key: string, prefix?: string): string; - - /** - * Get the value of a `SameSite` = `None` cookie, using the legacy `ss0-` prefix if needed. - * - * @param {string} key The key for the cookie - * @param {string?} prefix The prefix of the key. If undefined or null, `$wgCookiePrefix` is used - * @param {*} defaultValue A value to return if the cookie does not exist - * @returns {*} If the cookie exists, the value of the cookie, otherwise `defaultValue` - */ - function getCrossSite( - key: string, - prefix: string | undefined | null, - defaultValue: D - ): string | D; - function getCrossSite(key: string, prefix?: string): string; } } } diff --git a/mw/experiments.d.ts b/mw/experiments.d.ts index 09a96e3..41fd4da 100644 --- a/mw/experiments.d.ts +++ b/mw/experiments.d.ts @@ -25,7 +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 * // the A or B bucket. If the experiment were disabled, then the user would always be @@ -39,6 +39,7 @@ declare global { * B: 0.25 * } * } + * ``` * * @param {Object} experiment * @param {string} experiment.name The name of the experiment diff --git a/mw/hook.d.ts b/mw/hook.d.ts index f420465..bf6b2fd 100644 --- a/mw/hook.d.ts +++ b/mw/hook.d.ts @@ -17,7 +17,7 @@ import { User } from "./user"; * * Example usage: * - * ``` + * ```js * mw.hook( 'wikipage.content' ).add( fn ).remove( fn ); * mw.hook( 'wikipage.content' ).fire( $content ); * ``` @@ -33,7 +33,7 @@ import { User } from "./user"; * You can pass around the `add` and/or `fire` method to another piece of code * without it having to know the event name (or `mw.hook` for that matter). * - * ``` + * ```js * var h = mw.hook( 'bar.ready' ); * new mw.Foo( .. ).fetch( { callback: h.fire } ); * ``` @@ -49,6 +49,7 @@ interface Hook { * * @param {...Function} handler Function to bind. * @chainable + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.hook-method-add */ add(...handler: Array<(...data: T) => any>): this; @@ -57,6 +58,7 @@ interface Hook { * * @param {*} data * @chainable + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.hook-method-fire */ fire(...data: T): this; @@ -65,6 +67,7 @@ interface Hook { * * @param {...Function} handler Function to unbind. * @chainable + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.hook-method-remove */ remove(...handler: Array<(...data: T) => any>): this; } @@ -140,7 +143,7 @@ declare global { * * Code that fires the postEdit hook should first set `wgRevisionId` and `wgCurRevisionId` to the revision associated with the edit that triggered the postEdit hook, then fire the postEdit hook, e.g.: * - * ``` + * ```js * mw.config.set( { * wgCurRevisionId: data.newrevid, * wgRevisionId: data.newrevid @@ -300,7 +303,8 @@ declare global { * Create an instance of mw.hook, fired when the page watch status has changed. * * Example usage: - * ``` + * + * ```js * mw.hook( 'wikipage.watchlistChange' ).add( ( isWatched, expiry, expirySelected ) => { * // Do things * } ); @@ -315,9 +319,9 @@ declare global { /** * Create an instance of mw.hook. * - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.hook + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-hook */ - function hook(name: string): Hook; + function hook(event: string): Hook; } } diff --git a/mw/html.d.ts b/mw/html.d.ts index 75ca4cd..fe52a43 100644 --- a/mw/html.d.ts +++ b/mw/html.d.ts @@ -1,6 +1,18 @@ declare global { namespace mw { /** + * HTML construction helper functions + * + * ```js + * var Html, output; + * + * Html = mw.html; + * output = Html.element( 'div', {}, new Html.Raw( + * Html.element( 'img', { src: '<' } ) + * ) ); + * mw.log( output ); //
+ * ``` + * * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.html */ namespace html { @@ -28,8 +40,10 @@ declare global { * * Converts special characters to HTML entities. * - * mw.html.escape( '< > \' & "' ); - * // Returns < > ' & " + * ```js + * mw.html.escape( '< > \' & "' ); + * // Returns < > ' & " + * ``` * * @param {string} s The string to escape * @return {string} HTML @@ -38,10 +52,8 @@ declare global { function escape(s: string): string; /** - * Wrapper object for raw HTML passed to mw.html.element(). + * Wrapper object for raw HTML passed to {@link mw.html.element()}. * - * @class mw.html.Raw - * @constructor * @param {string} value * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.html.Raw-method-constructor */ diff --git a/mw/index.d.ts b/mw/index.d.ts index ffe3d7d..d32c7d1 100644 --- a/mw/index.d.ts +++ b/mw/index.d.ts @@ -29,10 +29,13 @@ declare global { * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw */ namespace mw { + // types for mw.widgets are out of scope! + const widgets: any; + /** * Format a string. Replace $1, $2 ... $N with positional arguments. * - * Used by Message#parser(). + * Used by {@link Message.parser()}. * * @since 1.25 * @param {string} formatString Format string @@ -94,9 +97,9 @@ declare global { * arranged from most general to most specific. Each path component should have a clear and * well-defined purpose. * - * Data handlers are registered via `mw.trackSubscribe`, and receive the full set of - * events that match their subscription, including those that fired before the handler was - * bound. + * Data handlers are registered via {@link mw.trackSubscribe}, and receive the full set of + * events that match their subscription, including buffered events that fired before the handler + * was subscribed. * * @param {string} topic Topic name * @param {Object|number|string} [data] Data describing the event. @@ -108,17 +111,29 @@ declare global { * * @private * @param {string} topic Topic name - * @param {Object} data Data describing the event, encoded as an object; see mw#logError + * @param {Object} data Data describing the event, encoded as an object; see {@link errorLogger.logError} */ function trackError(topic: string, data: object): void; /** * Register a handler for subset of analytic events, specified by topic. * - * Handlers will be called once for each tracked event, including any events that fired before the - * handler was registered; 'this' is set to a plain object with a topic' property naming the event, and a - * 'data' property which is an object of event-specific data. The event topic and event data are - * also passed to the callback as the first and second arguments, respectively. + * Handlers will be called once for each tracked event, including for any buffered events that + * fired before the handler was subscribed. The callback is passed a `topic` string, and optional + * `data` event object. The `this` value for the callback is a plain object with `topic` and + * `data` properties set to those same values. + * + * Example to monitor all topics for debugging: + * + * ```js + * mw.trackSubscribe( '', console.log ); + * ``` + * + * Example to subscribe to any of `foo.*`, e.g. both `foo.bar` and `foo.quux`: + * + * ```js + * mw.trackSubscribe( 'foo.', console.log ); + * ``` * * @param {string} topic Handle events whose name starts with this string prefix * @param {Function} callback Handler to call for each matching tracked event @@ -136,9 +151,6 @@ declare global { * @param {Function} callback */ function trackUnsubscribe(callback: (topic: string, data: object) => any): void; - - // types for mw.widgets are out of scope! - const widgets: any; } } diff --git a/mw/language.d.ts b/mw/language.d.ts index 44568e2..e62ab68 100644 --- a/mw/language.d.ts +++ b/mw/language.d.ts @@ -4,12 +4,10 @@ declare global { * Base language object with methods related to language support, attempting to mirror some of the * functionality of the Language class in MediaWiki: * - * - storing and retrieving language data - * - transforming message syntax (`{{PLURAL:}}`, `{{GRAMMAR:}}`, `{{GENDER:}}`) - * - formatting numbers + * - storing and retrieving language data + * - transforming message syntax (`{{PLURAL:}}`, `{{GRAMMAR:}}`, `{{GENDER:}}`) + * - formatting numbers * - * @class - * @singleton * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language */ namespace language { @@ -20,27 +18,31 @@ declare global { * * To set data: * - * // Override, extend or create the language data object of 'nl' - * mw.language.setData( 'nl', 'myKey', 'My value' ); + * ```js + * // Override, extend or create the language data object of 'nl' + * mw.language.setData( 'nl', 'myKey', 'My value' ); * - * // Set multiple key/values pairs at once - * mw.language.setData( 'nl', { foo: 'X', bar: 'Y' } ); + * // Set multiple key/values pairs at once + * mw.language.setData( 'nl', { foo: 'X', bar: 'Y' } ); + * ``` * * To get GrammarForms data for language 'nl': * - * var grammarForms = mw.language.getData( 'nl', 'grammarForms' ); + * ```js + * var grammarForms = mw.language.getData( 'nl', 'grammarForms' ); + * ``` * * Possible data keys: * - * - `digitTransformTable` - * - `separatorTransformTable` - * - `minimumGroupingDigits` - * - `grammarForms` - * - `pluralRules` - * - `digitGroupingPattern` - * - `fallbackLanguages` - * - `bcp47Map` - * - `languageNames` + * - `digitTransformTable` + * - `separatorTransformTable` + * - `minimumGroupingDigits` + * - `grammarForms` + * - `pluralRules` + * - `digitGroupingPattern` + * - `fallbackLanguages` + * - `bcp47Map` + * - `languageNames` * * @property {Object} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-property-data @@ -90,7 +92,7 @@ declare global { function convertGrammar(word: string, form: string): string; /** - * Converts a number using #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 @@ -117,13 +119,11 @@ declare global { /** * Helper function to flip transformation tables. * - * @param {...Object} Transformation tables + * @param {...Object} tables Transformation tables * @return {Object} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-flipTransform */ - function flipTransform( - ...Transformation: Array> - ): Record; + function flipTransform(...tables: Array>): Record; /** * Provides an alternative text depending on specified gender. @@ -238,7 +238,9 @@ declare global { * * Example: Fill the string to length 10 with '+' characters on the right. * - * pad( 'blah', 10, '+', true ); // => 'blah++++++' + * ```js + * pad( 'blah', 10, '+', true ); // => 'blah++++++' + * ``` * * @private * @param {string} text The string to pad diff --git a/mw/loader.d.ts b/mw/loader.d.ts index 9b48087..0ea5313 100644 --- a/mw/loader.d.ts +++ b/mw/loader.d.ts @@ -10,8 +10,6 @@ declare global { * For more information, refer to * * - * @class mw.loader - * @singleton * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.loader */ namespace loader { @@ -40,16 +38,18 @@ declare global { * * Example: * - * mw.loader.getScript( - * 'https://example.org/x-1.0.0.js' - * ) - * .then( function () { - * // Script succeeded. You can use X now. - * }, function ( e ) { - * // Script failed. X is not avaiable - * mw.log.error( e.message ); // => "Failed to load script" - * } ); + * ```js + * mw.loader.getScript( + * 'https://example.org/x-1.0.0.js' + * ) + * .then( function () { + * // Script succeeded. You can use X now. + * }, function ( e ) { + * // Script failed. X is not avaiable + * mw.log.error( e.message ); // => "Failed to load script" * } ); + * } ); + * ``` * * @member mw.loader * @param {string} url Script URL @@ -61,6 +61,15 @@ declare global { /** * Get the state of a module. * + * Possible states for the public API: + * + * - `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. + * - `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. + * * @param {string} module Name of module * @return {string|null} The state, or null if the module (or its state) is not * in the registry. @@ -68,6 +77,46 @@ declare global { */ function getState(module: string): string | null; + /** + * Implement a module given the components of the module. + * + * See {@link impl} for a full description of the parameters. + * + * Prior to MW 1.41, this was used internally, but now it is only kept + * for backwards compatibility. + * + * Does not support mw.loader.store caching. + * + * @param {string} module + * @param {Function|Array|string|Object} [script] Module code. This can be a function, + * a list of URLs to load via `