From d9d32c66a092fd163431b417191a113028ba0e1e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adrien=20LES=C3=89N=C3=89CHAL?= Date: Sat, 5 Oct 2024 10:37:24 +0200 Subject: [PATCH] JSdoc fixes mw: - use `function` decls instead of `Function`, with detailed arguments when possible - use `@since` with changes specified directly in method descriptions - use more `@example` vue: - link to online doc instead of source code in `@see` (online doc has a link to the source code anyway) - replace `@return` with `@returns` for consistency --- jquery/textSelection.d.ts | 2 +- mw/Api.d.ts | 11 ++++++----- mw/Title.d.ts | 10 ++++------ mw/Uri.d.ts | 2 +- mw/global.d.ts | 2 +- mw/language.d.ts | 2 +- mw/loader.d.ts | 28 ++++++++++++---------------- mw/log.d.ts | 2 +- mw/storage.d.ts | 3 ++- vue/index.d.ts | 8 ++++---- 10 files changed, 33 insertions(+), 37 deletions(-) diff --git a/jquery/textSelection.d.ts b/jquery/textSelection.d.ts index 1614837..0678bce 100644 --- a/jquery/textSelection.d.ts +++ b/jquery/textSelection.d.ts @@ -112,7 +112,7 @@ declare global { * Provided by the `jquery.textSelection` ResourceLoader module. * * @param {string} command Command to execute - * @param {Object.} functions Functions to replace. Keys are command names (as in {@link textSelection}, + * @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. * @see https://doc.wikimedia.org/mediawiki-core/master/js/jQueryPlugins.html#.textSelection diff --git a/mw/Api.d.ts b/mw/Api.d.ts index daf246e..726d65d 100644 --- a/mw/Api.d.ts +++ b/mw/Api.d.ts @@ -14,7 +14,7 @@ import { TitleLike } from "./Title"; type TypeOrArray = T extends any ? T | T[] : never; // T[] would be a mixed array type ReplaceValue = T extends U[] ? V[] : V; -type UnknownApiParams = Record; +type UnknownApiParams = Record; export type ApiResponse = Record; // it will always be a JSON object, the rest is uncertain ... @@ -100,7 +100,7 @@ declare global { * } ); * ``` * - * Since MW 1.25, multiple values for a parameter can be specified using an array: + * @since 1.25 - multiple values for a parameter can be specified using an array: * * ```js * var api = new mw.Api(); @@ -112,10 +112,9 @@ declare global { * } ); * ``` * - * Since MW 1.26, boolean values for API parameters can be specified natively. Parameter + * @since 1.26 - boolean values for API parameters can be specified natively. Parameter * values set to `false` or `undefined` will be omitted from the request, as required by * the API. - * * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.Api.html */ class Api { @@ -435,8 +434,10 @@ declare global { * Get a token for a certain action from the API. * * @since 1.22 + * @since 1.25 - assert parameter can be passed. + * @since 1.35 - additional parameters can be passed as an object instead of `assert`. * @param {string} type Token type - * @param {ApiQueryTokensParams|ApiAssert} [additionalParams] Additional parameters for the API (since 1.35). When given a string, it's treated as the `assert` parameter (since 1.25). + * @param {ApiQueryTokensParams|ApiAssert} [additionalParams] Additional parameters for the API. When given a string, it's treated as the `assert` parameter. * @returns {JQuery.Promise} Received token. * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.Api.html#getToken */ diff --git a/mw/Title.d.ts b/mw/Title.d.ts index 2941e65..b95d153 100644 --- a/mw/Title.d.ts +++ b/mw/Title.d.ts @@ -14,18 +14,16 @@ interface TitleExistenceStore { /** * The setter function. Returns a boolean. * - * Example to declare existing titles: - * + * @example * ```js + * // To declare existing titles * Title.exist.set( ['User:John_Doe', ...] ); * ``` - * - * Example to declare titles nonexistent: - * + * @example * ```js + * // To declare titles nonexistent * Title.exist.set( ['File:Foo_bar.jpg', ...], false ); * ``` - * * @param {string|string[]} titles Title(s) in strict prefixedDb title form * @param {boolean} [state=true] State of the given titles * @returns {boolean} diff --git a/mw/Uri.d.ts b/mw/Uri.d.ts index 4647dfc..ac374f1 100644 --- a/mw/Uri.d.ts +++ b/mw/Uri.d.ts @@ -11,7 +11,7 @@ declare global { * A factory method to create an {@link mw.Uri} class with a default location to resolve relative URLs * against (including protocol-relative URLs). * - * @param {string|Function} documentLocation A full url, or function returning one. + * @param {string|function():string} documentLocation A full url, or function returning one. * If passed a function, the return value may change over time and this will be honoured. (T74334) * @returns {Function} An mw.Uri class constructor * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.html#.UriRelative diff --git a/mw/global.d.ts b/mw/global.d.ts index bd6873e..dde6aac 100644 --- a/mw/global.d.ts +++ b/mw/global.d.ts @@ -3,7 +3,7 @@ declare global { * Schedule a function to run once the page is ready (DOM loaded). * * @since 1.5.8 - * @param {Function} fn + * @param {function():void} fn * @see https://doc.wikimedia.org/mediawiki-core/master/js/window.html#.addOnloadHook */ function addOnloadHook(fn: () => void): void; diff --git a/mw/language.d.ts b/mw/language.d.ts index 48c197c..022da3d 100644 --- a/mw/language.d.ts +++ b/mw/language.d.ts @@ -72,7 +72,7 @@ declare global { * @param {string} pattern Pattern string as described by Unicode TR35 * @param {number|null} [minimumGroupingDigits=null] * @throws {Error} If unable to find a number expression in `pattern`. - * @return {string} + * @returns {string} */ function commafy( value: number, diff --git a/mw/loader.d.ts b/mw/loader.d.ts index 6805529..1c43080 100644 --- a/mw/loader.d.ts +++ b/mw/loader.d.ts @@ -215,30 +215,26 @@ declare global { * And any on-going requests from other dependencies or using() calls are also * automatically re-used. * - * Example of inline dependency on OOjs: - * + * @example * ```js + * // Inline dependency on OOjs * mw.loader.using( 'oojs', function () { * OO.compare( [ 1 ], [ 1 ] ); * } ); * ``` - * - * Example of inline dependency obtained via `require()`: - * + * @example * ```js + * // Inline dependency obtained via require() * mw.loader.using( [ 'mediawiki.util' ], function ( require ) { * var util = require( 'mediawiki.util' ); * } ); * ``` - * - * Since MediaWiki 1.23 this returns a promise. - * - * Since MediaWiki 1.28 the promise is resolved with a `require` function. - * + * @since 1.23 - this returns a promise. + * @since 1.28 - the promise is resolved with a `require` function. * @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 + * @param {function(ModuleRequire):void} [ready] Callback to execute when all dependencies are ready + * @param {function(Error, ...any):void} [error] Callback to execute if one or more dependencies failed * @returns {JQuery.Promise} With a `require` function * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.loader.html#.using */ @@ -283,7 +279,7 @@ declare global { * * @private * @param {string} src URL to script, will be used as the src attribute in the script tag - * @param {Function} [callback] Callback to run after request resolution + * @param {function():void} [callback] Callback to run after request resolution * @param {string[]} [modules] List of modules being requested, for state to be marked as error * in case the script fails to load * @returns {HTMLScriptElement} @@ -316,8 +312,8 @@ declare global { * * @private * @param {string[]} dependencies Array of module names in the registry - * @param {Function} [ready] Callback to execute when all dependencies are ready - * @param {Function} [error] Callback to execute when any dependency fails + * @param {function():void} [ready] Callback to execute when all dependencies are ready + * @param {function(Error, ...any):void} [error] Callback to execute when any dependency fails */ function enqueue( dependencies: string[], @@ -456,7 +452,7 @@ declare global { * please use the dynamically provided `require()` function instead. * * In case of lazy-loaded modules via {@link mw.loader.using()}, the returned - * Promise provides the function, see using() for examples. + * Promise provides the function, see {@link mw.loader.using using()} for examples. * * @since 1.27 * @private diff --git a/mw/log.d.ts b/mw/log.d.ts index ed17f5e..6569282 100644 --- a/mw/log.d.ts +++ b/mw/log.d.ts @@ -79,7 +79,7 @@ declare global { * @param {string|null} key Name of the feature for deprecation tracker, * or null for a console-only deprecation. * @param {string} msg Deprecation warning. - * @returns {Function} + * @returns {function():void} * @see https://doc.wikimedia.org/mediawiki-core/master/js/mw.log.html#.makeDeprecated */ function makeDeprecated(key: string | null, msg: string): () => void; diff --git a/mw/storage.d.ts b/mw/storage.d.ts index f3f2b30..5be050c 100644 --- a/mw/storage.d.ts +++ b/mw/storage.d.ts @@ -51,11 +51,12 @@ interface SafeStorage { /** * Set the expiry time for an item in the store. * + * @since 1.41 - returns a boolean indicating whether the expiry was set. * @param {string} key Key name * @param {number} [expiry] Number of seconds after which this item can be deleted, * omit to clear the expiry (either making the item never expire, or to clean up * when deleting a key). - * @returns {boolean} The expiry was set (or cleared) [since 1.41] + * @returns {boolean} The expiry was set (or cleared) * @see https://doc.wikimedia.org/mediawiki-core/master/js/module-mediawiki.storage-SafeStorage.html#setExpires */ setExpires(key: string, expiry?: number): boolean; diff --git a/vue/index.d.ts b/vue/index.d.ts index f404754..e66feb1 100644 --- a/vue/index.d.ts +++ b/vue/index.d.ts @@ -13,9 +13,9 @@ declare module "vue" { * * @method createMwApp * @param {...any} args - * @return {Object} Vue app instance + * @returns {Object} Vue app instance * @memberof module:vue - * @see {@link https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/core/+/25026db6cc45d72ce7433d08c6632c03d0e60aee/resources/src/vue/index.js#29} + * @see {@link https://doc.wikimedia.org/mediawiki-core/master/js/module-vue.html#.createMwApp} */ export const createMwApp: typeof createApp; @@ -38,9 +38,9 @@ declare module "vue" { * * @param {string} key Key of message to get * @param {...any} parameters Values for $N replacements - * @return {mw.Message} + * @returns {mw.Message} * @memberof module:vue.prototype - * @see {@link https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/core/+/25026db6cc45d72ce7433d08c6632c03d0e60aee/resources/src/vue/i18n.js#31} + * @see {@link https://doc.wikimedia.org/mediawiki-core/master/js/module-vue.html#$i18n} */ $i18n: (key: string, ...parameters: any[]) => mw.Message; }