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
wikimedia-gadgets · Feb 28, 2024 · 0ea86ed · 0ea86ed
1 parent 0982415
commit 0ea86ed
Show file tree

Hide file tree

Showing 10 changed files with 75 additions and 49 deletions.
diff --git 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<ApiResponse>} API promise for the final upload.
      */
     (data?: ApiUploadParams): JQuery.Promise<ApiResponse>;
 }
@@ -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<ApiResponse>;
 
             /**
-             * 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<ApiResponse>} 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<ApiResponse>} 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<ApiResponse>;
 
             /**
-             * 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<ApiResponse>}
+             * @returns {JQuery.Promise<ApiResponse>} 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<ApiResponse>}
              * @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<EditResult>}
+             * @returns {JQuery.Promise<EditResult>} 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<ApiResponse>;
 
             /**
-             * 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<Partial<Record<T, string>>>}
+             * @returns {JQuery.Promise<Object.<string, string>>}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.messages-method-getMessages
              */
             getMessages<T extends string>(
@@ -711,7 +735,7 @@ declare global {
             /**
              * @param {string} username
              * @param {string} password
-             * @returns {JQuery.Promise<ApiResponse>}
+             * @returns {JQuery.Promise<ApiResponse>} 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<ApiResponse>;

diff --git 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<RestResponse>} API response data and the jqXHR object
+             * @returns {JQuery.Promise<RestResponse>} 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<RestResponse>;

diff --git 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
@@ -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
@@ -48,36 +48,6 @@ declare global {
              */
             const data: Record<string, Map>;
 
-            /**
-             * 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
@@ -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<T extends string, U extends T = T>(modules: U[]): T[];
 
             /**

diff --git 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
@@ -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
@@ -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
@@ -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