Skip to content

Commit

Permalink
Cleanup comments
Browse files Browse the repository at this point in the history 
- add missing annotations as suggested by @AnYiEE
- add missing `@see` annotations
- synchronize JSdoc types with TS types
- unify `@return`/`@returns` annotations
- unify `*`/`any`/`Mixed` types
- remove redundant `@chainable`/`@member`/`@method`/`@private`/`@property`/`@returns {void}` annotations
  • Loading branch information
Adrien LESÉNÉCHAL committed Jan 29, 2024
1 parent 4f5be75 commit c394fb3
Show file tree
Hide file tree
Showing 27 changed files with 277 additions and 304 deletions.
12 changes: 8 additions & 4 deletions jquery/client.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@ declare global {
interface JQueryStatic {
/**
* User-agent detection
*
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.client
*/
client: Client;
}
Expand Down Expand Up @@ -74,9 +76,10 @@ interface Client {
* - `solaris` (untested)
* - `win`
*
* @param {Object} [nav] An object with a 'userAgent' and 'platform' property.
* @param {ClientNavigator} [nav] An object with a 'userAgent' and 'platform' property.
* Defaults to the global `navigator` object.
* @return {Object} The client object
* @returns {ClientProfile} The client object
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.client-method-profile
*/
profile(nav?: ClientNavigator): ClientProfile;

Expand Down Expand Up @@ -117,10 +120,11 @@ interface Client {
* ```
*
* @param {Object} map Browser support map
* @param {Object} [profile] A client-profile object
* @param {ClientProfile} [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
* @returns {boolean} The current browser is in the support map
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.client-method-test
*/
test(
map: ClientSupportMap | { ltr: ClientSupportMap; rtl: ClientSupportMap },
Expand Down
10 changes: 4 additions & 6 deletions jquery/colorUtil.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ interface ColorUtil {
* <http://jquery.offput.ca/highlightFade/>
*
* @param {Array|string} color
* @return {Array}
* @returns {Array}
*/
getRGB(color: string | number[]): number[];

Expand All @@ -21,8 +21,6 @@ interface ColorUtil {
*
* Based on Interface by Stefan Petre
* <http://interface.eyecon.ro/>
*
* @property {Object}
*/
colors: Record<string, [number, number, number]>;

Expand All @@ -40,7 +38,7 @@ interface ColorUtil {
* @param {number} r The red color value
* @param {number} g The green color value
* @param {number} b The blue color value
* @return {number[]} The HSL representation
* @returns {number[]} The HSL representation
*/
rgbToHsl(r: number, g: number, b: number): number[];

Expand All @@ -58,7 +56,7 @@ interface ColorUtil {
* @param {number} h The hue
* @param {number} s The saturation
* @param {number} l The lightness
* @return {number[]} The RGB representation
* @returns {number[]} The RGB representation
*/
hslToRgb(h: number, s: number, l: number): number[];

Expand All @@ -76,7 +74,7 @@ interface ColorUtil {
*
* @param {Mixed} currentColor Current value in css
* @param {number} mod Wanted brightness modification between -1 and 1
* @return {string} Like `'rgb(r,g,b)'`
* @returns {string} Like `'rgb(r,g,b)'`
*/
getColorBrightness(currentColor: any, mod: number): `rgb(${number},${number},${number})`;
}
Expand Down
47 changes: 27 additions & 20 deletions jquery/textSelection.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@ declare global {
* Get the contents of the textarea.
*
* @param {string} command Command to execute
* @return {string}
* @returns {string}
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection
*/
textSelection(command: "getContents"): string;

Expand All @@ -13,16 +14,17 @@ declare global {
*
* @param {string} command Command to execute
* @param {string} content
* @return {JQuery}
* @chainable
* @returns {JQuery}
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection
*/
textSelection(command: "setContents", content: string): this;

/**
* Get the currently selected text in this textarea.
*
* @param {string} command Command to execute
* @return {string}
* @returns {string}
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection
*/
textSelection(command: "getSelection"): string;

Expand All @@ -31,8 +33,8 @@ declare global {
*
* @param {string} command Command to execute
* @param {string} value
* @return {JQuery}
* @chainable
* @returns {JQuery}
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection
*/
textSelection(command: "replaceSelection", value: string): this;

Expand All @@ -43,9 +45,9 @@ declare global {
* Also focusses the textarea.
*
* @param {string} command Command to execute
* @param {Object} [options]
* @return {JQuery}
* @chainable
* @param {TextSelectionEncapsulateOptions} [options]
* @returns {JQuery}
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection
*/
textSelection(
command: "encapsulateSelection",
Expand All @@ -57,8 +59,9 @@ declare global {
*
* @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
* @param {boolean} [options.startAndEnd=false] Return range of the selection rather than just start
* @returns {number[]} Array with two numbers, for start and end of selection
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection
*/
textSelection(
command: "getCaretPosition",
Expand All @@ -70,8 +73,9 @@ declare global {
*
* @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}
* @param {boolean} [options.startAndEnd=false] Return range of the selection rather than just start
* @returns {number}
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection
*/
textSelection(command: "getCaretPosition", options?: { startAndEnd?: false }): number;

Expand All @@ -82,8 +86,8 @@ declare global {
* @param {Object} options
* @param {number} options.start
* @param {number} [options.end=options.start]
* @return {JQuery}
* @chainable
* @returns {JQuery}
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection
*/
textSelection(command: "setSelection", options: { start: number; end?: number }): this;

Expand All @@ -93,20 +97,21 @@ declare global {
*
* @param {string} command Command to execute
* @param {Object} [options]
* @param {string} [options.force=false] Whether to force a scroll even if the caret position
* @param {boolean} [options.force=false] Whether to force a scroll even if the caret position
* is already visible.
* @return {JQuery}
* @chainable
* @returns {JQuery}
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection
*/
textSelection(command: "scrollToCaretPosition", options: { force?: boolean }): this;

/**
* 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},
* @param {Object.<string, Function>} 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/#!/api/jQuery.plugin.textSelection-method-textSelection
*/
textSelection(
command: "register",
Expand All @@ -117,6 +122,7 @@ declare global {
* Unregister the alternative textSelection API for this element (see 'register').
*
* @param {string} command Command to execute
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection
*/
textSelection(command: "unregister"): void;

Expand All @@ -125,7 +131,8 @@ declare global {
*
* @param {string} command Command to execute
* @param {Mixed} [commandOptions] Options to pass to the command
* @return {Mixed} Depending on the command
* @returns {Mixed} Depending on the command
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection
*/
textSelection(command: string, commandOptions?: any): void;
}
Expand Down
30 changes: 11 additions & 19 deletions mw/Api.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ import {
ApiRollbackParams,
ApiUploadParams,
} from "../api_params";
import { TitleLike } from "./Title";
import { UserInfo } from "./user";

type TitleLike = string | mw.Title;
type TitleLikeArray = string[] | mw.Title[]; // TitleLike[] would be a mixed array
type ApiParams = Record<string, string | string[] | boolean | number | number[]>;
type ApiResponse = Record<string, any>; // it will always be a JSON object, the rest is uncertain ...
Expand Down Expand Up @@ -72,15 +72,11 @@ declare global {
*/
constructor(options?: ApiOptions);

/**
* @private
*/
defaults: ApiOptions;
private defaults: ApiOptions;

/**
* Abort all unfinished requests issued by this Api object.
*
* @returns {void}
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-abort
*/
abort(): void;
Expand Down Expand Up @@ -114,10 +110,8 @@ declare global {
/**
* Massage parameters from the nice format we accept into a format suitable for the API.
*
* @private
* @param {ApiParams} parameters (modified in-place)
* @param {boolean} useUS Whether to use U+001F when joining multi-valued parameters.
* @returns {void}
*/
private preprocessParameters(parameters: ApiParams, useUS: boolean): void;

Expand Down Expand Up @@ -164,7 +158,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<string>} Received token
* @since 1.22
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-getToken
Expand All @@ -179,7 +173,6 @@ declare global {
* automatically.
*
* @param {string} type Token type
* @returns {void}
* @since 1.26
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-badToken
*/
Expand Down Expand Up @@ -217,7 +210,7 @@ declare global {
* } );
* ```
*
* @param {Object} data API response indicating an error
* @param {ApiResponse} data API response indicating an error
* @returns {JQuery} Error messages, each wrapped in a `<div>`
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-getErrorMessage
*/
Expand Down Expand Up @@ -324,7 +317,7 @@ declare global {
* ```
*
* @param {TitleLike} title Page title
* @param {(data: { timestamp: string, content: string }) => string | ApiEditPageParams} transform Callback that prepares the edit
* @param {function({ timestamp: string, content: string }):string|ApiEditPageParams} transform Callback that prepares the edit
* @returns {JQuery.Promise<any>}
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.edit-method-edit
*/
Expand Down Expand Up @@ -516,10 +509,10 @@ declare global {
* Get the categories that a particular page on the wiki belongs to.
*
* @param {TitleLike} title
* @returns {JQuery.Promise<false | mw.Title[]>} List of category titles or false if title was not found
* @returns {JQuery.Promise<false|Title[]>} List of category titles or false if title was not found
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.category-method-getCategories
*/
getCategories(title: TitleLike): JQuery.Promise<false | mw.Title[]>;
getCategories(title: TitleLike): JQuery.Promise<false | Title[]>;

/**
* Convenience method for `action=rollback`.
Expand Down Expand Up @@ -558,7 +551,7 @@ declare global {
*
* This function will return a promise that will resolve with a function to finish the stash upload.
*
* @param {File | HTMLInputElement} file
* @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)
Expand All @@ -577,9 +570,9 @@ declare global {
*
* The file will be uploaded using AJAX and FormData.
*
* @param {HTMLInputElement | File | Blob} file HTML `input type=file` element with a file already inside of it, or a File object.
* @param {File|Blob|HTMLInputElement} file HTML `input type=file` element with a file already inside of it, or a File object.
* @param {ApiUploadParams} data Other upload options, see `action=upload` API docs for more
* @return {JQuery.Promise<ApiResponse>}
* @returns {JQuery.Promise<ApiResponse>}
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.upload-method-upload
*/
upload(
Expand Down Expand Up @@ -613,9 +606,8 @@ declare global {
* } );
* ```
*
* @param {File | HTMLInputElement} file
* @param {File|HTMLInputElement} file
* @param {ApiUploadParams} [data]
* @return {JQuery.Promise}
* @returns {JQuery.Promise<(data?: ApiUploadParams) => JQuery.Promise<ApiResponse>>} Call this function to finish the upload
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.upload-method-uploadToStash
*/
Expand Down
2 changes: 1 addition & 1 deletion mw/ForeignApi.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ declare global {
* Return the origin to use for API requests, in the required format (protocol, host and port, if any).
*
* @protected
* @return {string | undefined}
* @returns {string|undefined}
*/
protected getOrigin(): string | undefined;
}
Expand Down
2 changes: 1 addition & 1 deletion mw/ForeignRest.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ declare global {
* @param {string | Uri} url URL pointing to another wiki's rest.php endpoint.
* @param {ForeignApi} foreignActionApi
* @param {ForeignRestOptions} [options]
* @since 1.26
* @since 1.36
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignApi-method-constructor
*/
constructor(
Expand Down
20 changes: 10 additions & 10 deletions mw/Map.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,15 @@ declare global {
class Map<V extends Record<string, any> = any> {
private values: V;

/**
* 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
*/
exists(selection: keyof V): boolean;

/**
* Get the value of one or more keys.
*
Expand All @@ -23,9 +32,9 @@ declare global {
* an object of key/values. If no selection is passed, a new object with all key/values is returned.
* @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Map-method-get
*/
get(): V;
get<S extends keyof V>(selection: S[], fallback?: any): Pick<V, S>;
get<S extends keyof V>(selection: S, fallback?: V[S]): V[S];
get(): V;

/**
* Set the value of one or more keys.
Expand All @@ -37,15 +46,6 @@ declare global {
*/
set<S extends keyof V>(selection: S, value: V[S]): boolean;
set(selection: Partial<V>): boolean;

/**
* 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
*/
exists(selection: keyof V): boolean;
}
}
}
Expand Down
Loading

0 comments on commit c394fb3

Please sign in to comment.