From 31e20c889e467aa4ba64b0b5baf602adc1359371 Mon Sep 17 00:00:00 2001 From: toasted-nutbread Date: Fri, 20 May 2022 10:28:38 -0400 Subject: 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 --- ext/js/input/hotkey-handler.js | 42 +++++++++++++++++++++++++----------------- ext/js/input/hotkey-util.js | 36 +++++++++++++++++++----------------- 2 files changed, 44 insertions(+), 34 deletions(-) (limited to 'ext/js/input') 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 @@ -23,6 +23,16 @@ * Class which handles hotkey events and actions. */ 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. */ @@ -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; -- cgit v1.2.3