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
wikimedia-gadgets · Oct 5, 2024 · d9d32c6 · d9d32c6
1 parent da1f686
commit d9d32c6
Show file tree

Hide file tree

Showing 10 changed files with 33 additions and 37 deletions.
diff --git 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.<string, Function>} functions Functions to replace. Keys are command names (as in {@link textSelection},
+         * @param {Object.<string, function(unknown):void>} 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
@@ -14,7 +14,7 @@ import { TitleLike } from "./Title";
 type TypeOrArray<T> = T extends any ? T | T[] : never; // T[] would be a mixed array
 type ReplaceValue<T extends U | U[], U, V> = T extends U[] ? V[] : V;
 
-type UnknownApiParams = Record<string, string | number | boolean | string[] | number[] | undefined>;
+type UnknownApiParams = Record<string, string | string[] | boolean | number | number[]>;
 
 export type ApiResponse = Record<string, any>; // 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<string>} 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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<ModuleRequire>} 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
@@ -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
@@ -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
@@ -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;
     }