Skip to content

Commit

Permalink
Cleanup & update comments
Browse files Browse the repository at this point in the history 
- add missing comments and update some comments to 1.41.
- use code blocks and specify language when possible.
- use @link when referencing other members
- fix use of null (`{T?} x`) instead of optional (`{T} [x]`) parameters in some cases
- remove redundant namespace prefixes
- remove redundant @class/@constructor/@extends/@property/@singleton/@static annotations
  • Loading branch information
Adrien LESÉNÉCHAL committed Jan 22, 2024
1 parent 773af71 commit 1b8807c
Show file tree
Hide file tree
Showing 29 changed files with 1,009 additions and 519 deletions.
3 changes: 1 addition & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.**

Expand Down Expand Up @@ -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.

80 changes: 45 additions & 35 deletions jquery/client.d.ts
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
declare global {
interface JQueryStatic {
/**
* User-agent detection
*/
client: Client;
}
}
Expand All @@ -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:
*
Expand Down Expand Up @@ -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;
Expand Down
16 changes: 12 additions & 4 deletions jquery/collapsibleTabs.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
10 changes: 6 additions & 4 deletions jquery/colorUtil.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions jquery/index.d.ts
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import "jquery";

import "./textSelection";
import "./collapsibleTabs";
import "./client";
import "./collapsibleTabs";
import "./colorUtil";
import "./textSelection";
125 changes: 99 additions & 26 deletions jquery/textSelection.d.ts
View file
Original file line number Diff line number Diff line change
@@ -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;
Expand All @@ -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<string, (...commandOptions: any[]) => 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<string, (...args: any[]) => any>): void;
}
}

Expand Down
Loading

0 comments on commit 1b8807c

Please sign in to comment.