aboutsummaryrefslogtreecommitdiff
path: root/ext/js/input
diff options
context:
space:
mode:
authortoasted-nutbread <toasted-nutbread@users.noreply.github.com>2022-05-20 10:28:38 -0400
committerGitHub <noreply@github.com>2022-05-20 10:28:38 -0400
commit31e20c889e467aa4ba64b0b5baf602adc1359371 (patch)
treea033db935a817b2d407ec20843176610a87a6e16 /ext/js/input
parentae0ad227c0fd293609a21e5cc1d2a4b85fe7c520 (diff)
ESlint JSdoc (#2148)
* Install eslint-plugin-jsdoc * Initial rules setup * Update lists * Use @returns rather than @return * Remove error throwing code which is never executed * Fix issues relating to @throws * General error fixes * Update Display type documentation * Various doc fixes * Fix invalid tuple syntax * Doc updates * Remove unused * Doc updates * Enable jsdoc/require-returns * Update rules * Update remaining rules
Diffstat (limited to 'ext/js/input')
-rw-r--r--ext/js/input/hotkey-handler.js42
-rw-r--r--ext/js/input/hotkey-util.js36
2 files changed, 44 insertions, 34 deletions
diff --git a/ext/js/input/hotkey-handler.js b/ext/js/input/hotkey-handler.js
index 33a449e3..dc0f6d3e 100644
--- a/ext/js/input/hotkey-handler.js
+++ b/ext/js/input/hotkey-handler.js
@@ -24,6 +24,16 @@
*/
class HotkeyHandler extends EventDispatcher {
/**
+ * Information describing a hotkey.
+ * @typedef {object} HotkeyDefinition
+ * @property {string} action A string indicating which action to perform.
+ * @property {string} key A keyboard key code indicating which key needs to be pressed.
+ * @property {string[]} modifiers An array of keyboard modifiers which also need to be pressed. Supports: `'alt', 'ctrl', 'shift', 'meta'`.
+ * @property {string[]} scopes An array of scopes for which the hotkey is valid. If this array does not contain `this.scope`, the hotkey will not be registered.
+ * @property {boolean} enabled A boolean indicating whether the hotkey is currently enabled.
+ */
+
+ /**
* Creates a new instance of the class.
*/
constructor() {
@@ -49,7 +59,7 @@ class HotkeyHandler extends EventDispatcher {
/**
* Registers a set of actions that this hotkey handler supports.
- * @param actions An array of `[name, handler]` entries, where `name` is a string and `handler` is a function.
+ * @param {*[][]} actions An array of `[name, handler]` entries, where `name` is a string and `handler` is a function.
*/
registerActions(actions) {
for (const [name, handler] of actions) {
@@ -59,13 +69,8 @@ class HotkeyHandler extends EventDispatcher {
/**
* Registers a set of hotkeys for a given scope.
- * @param scope The scope that the hotkey definitions must be for in order to be activated.
- * @param hotkeys An array of hotkey definitions of the format `{action, key, modifiers, scopes, enabled}`.
- * * `action` - a string indicating which action to perform.
- * * `key` - a keyboard key code indicating which key needs to be pressed.
- * * `modifiers` - an array of keyboard modifiers which also need to be pressed. Supports: `'alt', 'ctrl', 'shift', 'meta'`.
- * * `scopes` - an array of scopes for which the hotkey is valid. If this array does not contain `this.scope`, the hotkey will not be registered.
- * * `enabled` - a boolean indicating whether the hotkey is currently enabled.
+ * @param {string} scope The scope that the hotkey definitions must be for in order to be activated.
+ * @param {HotkeyDefinition[]} hotkeys An array of hotkey definitions.
*/
registerHotkeys(scope, hotkeys) {
let registrations = this._hotkeyRegistrations.get(scope);
@@ -79,6 +84,7 @@ class HotkeyHandler extends EventDispatcher {
/**
* Removes all registered hotkeys for a given scope.
+ * @param {string} scope The scope that the hotkey definitions were registered in.
*/
clearHotkeys(scope) {
const registrations = this._hotkeyRegistrations.get(scope);
@@ -91,7 +97,8 @@ class HotkeyHandler extends EventDispatcher {
/**
* Assigns a set of hotkeys for a given scope. This is an optimized shorthand for calling
* `clearHotkeys`, then calling `registerHotkeys`.
- * @see registerHotkeys for argument information.
+ * @param {string} scope The scope that the hotkey definitions must be for in order to be activated.
+ * @param {HotkeyDefinition[]} hotkeys An array of hotkey definitions.
*/
setHotkeys(scope, hotkeys) {
let registrations = this._hotkeyRegistrations.get(scope);
@@ -107,8 +114,9 @@ class HotkeyHandler extends EventDispatcher {
/**
* Adds a single event listener to a specific event.
- * @param eventName The string representing the event's name.
- * @param callback The event listener callback to add.
+ * @param {string} eventName The string representing the event's name.
+ * @param {Function} callback The event listener callback to add.
+ * @returns {void}
*/
on(eventName, callback) {
const result = super.on(eventName, callback);
@@ -119,9 +127,9 @@ class HotkeyHandler extends EventDispatcher {
/**
* Removes a single event listener from a specific event.
- * @param eventName The string representing the event's name.
- * @param callback The event listener callback to add.
- * @returns `true` if the callback was removed, `false` otherwise.
+ * @param {string} eventName The string representing the event's name.
+ * @param {Function} callback The event listener callback to add.
+ * @returns {boolean} `true` if the callback was removed, `false` otherwise.
*/
off(eventName, callback) {
const result = super.off(eventName, callback);
@@ -132,9 +140,9 @@ class HotkeyHandler extends EventDispatcher {
/**
* Attempts to simulate an action for a given combination of key and modifiers.
- * @param key A keyboard key code indicating which key needs to be pressed.
- * @param modifiers An array of keyboard modifiers which also need to be pressed. Supports: `'alt', 'ctrl', 'shift', 'meta'`.
- * @returns `true` if an action was performed, `false` otherwise.
+ * @param {string} key A keyboard key code indicating which key needs to be pressed.
+ * @param {string[]} modifiers An array of keyboard modifiers which also need to be pressed. Supports: `'alt', 'ctrl', 'shift', 'meta'`.
+ * @returns {boolean} `true` if an action was performed, `false` otherwise.
*/
simulate(key, modifiers) {
const hotkeyInfo = this._hotkeys.get(key);
diff --git a/ext/js/input/hotkey-util.js b/ext/js/input/hotkey-util.js
index 4dd9447a..35802106 100644
--- a/ext/js/input/hotkey-util.js
+++ b/ext/js/input/hotkey-util.js
@@ -21,6 +21,7 @@
class HotkeyUtil {
/**
* Creates a new instance.
+ * @param {?string} os The operating system for this instance.
*/
constructor(os=null) {
this._os = os;
@@ -41,6 +42,7 @@ class HotkeyUtil {
/**
* Gets the operating system for this instance.
* The operating system is used to display system-localized modifier key names.
+ * @type {?string}
*/
get os() {
return this._os;
@@ -48,7 +50,7 @@ class HotkeyUtil {
/**
* Sets the operating system for this instance.
- * @param value The value to assign.
+ * @param {?string} value The value to assign.
* Valid values are: win, mac, linux, openbsd, cros, android.
*/
set os(value) {
@@ -59,10 +61,10 @@ class HotkeyUtil {
/**
* Gets a display string for a key and a set of modifiers.
- * @param key The key code string, or `null` for no key.
- * @param modifiers An array of modifiers.
+ * @param {?string} key The key code string, or `null` for no key.
+ * @param {string[]} modifiers An array of modifiers.
* Valid values are: ctrl, alt, shift, meta, or mouseN, where N is an integer.
- * @returns A user-friendly string for the combination of key and modifiers.
+ * @returns {string} A user-friendly string for the combination of key and modifiers.
*/
getInputDisplayValue(key, modifiers) {
const separator = this._inputSeparator;
@@ -85,9 +87,9 @@ class HotkeyUtil {
/**
* Gets a display string for a single modifier.
- * @param modifier A string representing a modifier.
+ * @param {string} modifier A string representing a modifier.
* Valid values are: ctrl, alt, shift, meta, or mouseN, where N is an integer.
- * @returns A user-friendly string for the modifier.
+ * @returns {string} A user-friendly string for the modifier.
*/
getModifierDisplayValue(modifier) {
const match = this._mouseInputNamePattern.exec(modifier);
@@ -101,8 +103,8 @@ class HotkeyUtil {
/**
* Gets a display string for a key.
- * @param key The key code string, or `null` for no key.
- * @returns A user-friendly string for the combination of key and modifiers, or `null` if key was already `null`.
+ * @param {?string} key The key code string, or `null` for no key.
+ * @returns {?string} A user-friendly string for the combination of key and modifiers, or `null` if key was already `null`.
*/
getKeyDisplayValue(key) {
if (typeof key === 'string' && key.length === 4 && key.startsWith('Key')) {
@@ -113,9 +115,9 @@ class HotkeyUtil {
/**
* Gets a display string for a single modifier.
- * @param modifier A string representing a modifier.
+ * @param {string} modifier A string representing a modifier.
* Valid values are: ctrl, alt, shift, meta, or mouseN, where N is an integer.
- * @returns `'mouse'` if the modifier represents a mouse button, `'key'` otherwise.
+ * @returns {'mouse'|'key'} `'mouse'` if the modifier represents a mouse button, `'key'` otherwise.
*/
getModifierType(modifier) {
return (this._mouseInputNamePattern.test(modifier) ? 'mouse' : 'key');
@@ -123,8 +125,8 @@ class HotkeyUtil {
/**
* Converts an extension command string into a standard input.
- * @param command An extension command string.
- * @returns An object `{key, modifiers}`, where key is a string (or `null`) representing the key, and modifiers is an array of modifier keys.
+ * @param {string} command An extension command string.
+ * @returns {{key: ?string, modifiers: string[]}} An object `{key, modifiers}`, where key is a string (or `null`) representing the key, and modifiers is an array of modifier keys.
*/
convertCommandToInput(command) {
let key = null;
@@ -142,10 +144,10 @@ class HotkeyUtil {
/**
* Gets a command string for a specified input.
- * @param key The key code string, or `null` for no key.
- * @param modifiers An array of modifier keys.
+ * @param {?string} key The key code string, or `null` for no key.
+ * @param {string[]} modifiers An array of modifier keys.
* Valid values are: ctrl, alt, shift, meta.
- * @returns An extension command string representing the input.
+ * @returns {string} An extension command string representing the input.
*/
convertInputToCommand(key, modifiers) {
const separator = '+';
@@ -168,9 +170,9 @@ class HotkeyUtil {
/**
* Sorts an array of modifiers.
- * @param modifiers An array of modifiers.
+ * @param {string[]} modifiers An array of modifiers.
* Valid values are: ctrl, alt, shift, meta.
- * @returns A sorted array of modifiers. The array instance is the same as the input array.
+ * @returns {string[]} A sorted array of modifiers. The array instance is the same as the input array.
*/
sortModifiers(modifiers) {
const pattern = this._mouseInputNamePattern;