chore: Remove jsdoc hyphens (#1947)

Author: marcustyphoon

eslint.config.js

@@ -33,6 +33,11 @@ export default [
    */
   jsdoc.configs['flat/recommended'],
 
+  /**
+   * @see https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-hyphen-before-param-description.md
+   */
+  { rules: { 'jsdoc/require-hyphen-before-param-description': ['error', 'never', { tags: { '*': 'never' } }] } },
+
   /**
    * Do not require JSDoc on "main world" injected scripts, which have definitions
    * which make them look reusable but are only used by the `inject()` util.

src/features/mass_privater/index.js

@@ -22,8 +22,8 @@ const dateTimeFormat = new Intl.DateTimeFormat(document.documentElement.lang, {
 /**
  * Adds string elements between an array's items to format it as an English prose list.
  * The Oxford comma is included.
- * @param {any[]} array - Input array of any number of items
- * @param {string} andOr - String 'and' or 'or', used before the last item
+ * @param {any[]} array Input array of any number of items
+ * @param {string} andOr String 'and' or 'or', used before the last item
  * @returns {any[]} An array alternating between the input items and strings
  */
 const elementsAsList = (array, andOr) =>

src/utils/control_buttons.js

@@ -8,9 +8,9 @@ $('.xkit-control-button-container').remove();
 
 /**
  * Create a button template that can be cloned with cloneControlButton() for inserting into the controls of a post.
- * @param {string} symbolId - The name of the RemixIcon to use
- * @param {string} buttonClass - An extra class to identify the extension that added the button
- * @param {string} label - Descriptive text to be set as the button aria-label property and tooltip
+ * @param {string} symbolId The name of the RemixIcon to use
+ * @param {string} buttonClass An extra class to identify the extension that added the button
+ * @param {string} label Descriptive text to be set as the button aria-label property and tooltip
  * @returns {HTMLDivElement} A button that can be cloned with cloneControlButton()
  */
 export const createControlButtonTemplate = function (symbolId, buttonClass, label = '') {
@@ -25,10 +25,10 @@ export const createControlButtonTemplate = function (symbolId, buttonClass, labe
 
 /**
  * Create a deep-level clone of a button template that is ready to add to the page
- * @param {HTMLDivElement} template - A button template as returned by createControlButtonTemplate()
- * @param {object} events - An object of DOM Event names and handler functions,
+ * @param {HTMLDivElement} template A button template as returned by createControlButtonTemplate()
+ * @param {object} events An object of DOM Event names and handler functions,
  *                          e.g. { click: () => { alert('Hello!'); } }
- * @param {boolean} disabled - Whether to disable the button clone
+ * @param {boolean} disabled Whether to disable the button clone
  * @returns {HTMLDivElement} A clone of the button template, with the specified event handlers attached
  */
 export const cloneControlButton = function (template, events, disabled = false) {
@@ -43,7 +43,7 @@ const secondaryFooterRowClass = 'xkit-controls-row';
 
 /**
  * Adds a secondary footer row above the footer control buttons, similar to the one in the pre-2025 footer layout on editable posts.
- * @param {HTMLElement} postElement - The target post element
+ * @param {HTMLElement} postElement The target post element
  * @returns {HTMLDivElement} The inserted element
  */
 const addSecondaryFooterRow = postElement => {
@@ -57,9 +57,9 @@ const addSecondaryFooterRow = postElement => {
 
 /**
  * Inserts a control button into the post footer.
- * @param {HTMLElement} postElement - The target post element
- * @param {HTMLDivElement} clonedControlButton - Control button element to insert
- * @param {string} buttonClass - Button HTML class
+ * @param {HTMLElement} postElement The target post element
+ * @param {HTMLDivElement} clonedControlButton Control button element to insert
+ * @param {string} buttonClass Button HTML class
  * @returns {Promise<void>} Resolves when finished
  */
 export const insertControlButton = async (postElement, clonedControlButton, buttonClass) => {

src/utils/crypto.js

@@ -10,7 +10,7 @@ export const getRandomHexString = () => {
 /**
  * Get a hexadecimal SHA-256 hash of a given string
  * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest#converting_a_digest_to_a_hex_string
- * @param {string} data - A USVString containing the data to hash
+ * @param {string} data A USVString containing the data to hash
  * @returns {Promise<string>} Hexadecimal string representing the data's SHA-256 digest
  */
 export const sha256 = async data => {

src/utils/css_map.js

@@ -3,14 +3,14 @@ import { inject } from './inject.js';
 export const cssMap = await inject('/main_world/css_map.js');
 
 /**
- * @param {...string} keys - One or more element source names
+ * @param {...string} keys One or more element source names
  * @returns {string[]} An array of generated classnames from the CSS map
  */
 export const keyToClasses = (...keys) => keys.flatMap(key => cssMap[key]).filter(Boolean);
 
 /**
- * @param {...string} keys - One or more element source names
- * @returns {string} - A CSS :is() selector which targets all elements that match any of the given source names
+ * @param {...string} keys One or more element source names
+ * @returns {string} A CSS :is() selector which targets all elements that match any of the given source names
  */
 export const keyToCss = function (...keys) {
   const classes = keyToClasses(...keys);

src/utils/dom.js

@@ -4,10 +4,10 @@
 
 /**
  * Create elements with simple syntax
- * @param {string} tagName - Type of element to create
- * @param {Attributes} [attributes] - Property-value pairs to set as HTML/XML attributes (e.g. { href: '/' })
- * @param {Events} [events] - Property-value pairs to set as event listeners (e.g. { click: () => {} })
- * @param {Children} [children] - Zero or more valid children
+ * @param {string} tagName Type of element to create
+ * @param {Attributes} [attributes] Property-value pairs to set as HTML/XML attributes (e.g. { href: '/' })
+ * @param {Events} [events] Property-value pairs to set as event listeners (e.g. { click: () => {} })
+ * @param {Children} [children] Zero or more valid children
  * @returns {HTMLElement | SVGElement | MathMLElement} Element created to specification
  */
 export function dom (tagName, attributes = {}, events = {}, children = []) {

src/utils/inject.js

@@ -3,9 +3,9 @@
  * This permits access to variables exposed by the Tumblr web platform that are normally inaccessible
  * in the content script sandbox.
  * See the src/main_world directory and [../main_world/index.js](../main_world/index.js).
- * @param {string} path - Absolute path of script to inject (will be fed to `runtime.getURL()`)
- * @param {Array} [args] - Array of arguments to pass to the script
- * @param {Element} [target] - Target element; will be accessible as the `this` value in the injected function.
+ * @param {string} path Absolute path of script to inject (will be fed to `runtime.getURL()`)
+ * @param {Array} [args] Array of arguments to pass to the script
+ * @param {Element} [target] Target element; will be accessible as the `this` value in the injected function.
  * @returns {Promise<any>} The transmitted result of the script
  */
 export const inject = (path, args = [], target = document.documentElement) =>

src/utils/interface.js

@@ -37,15 +37,15 @@ export const getPopoverWrapper = element => {
 
 /**
  * @typedef {object} PostFilterOptions
- * @property {string} [excludeClass] - Classname to exclude and add
- * @property {Function|Function[]} [timeline] - Filter results to matching timeline element children
- * @property {boolean} [noBlogView] - Whether to exclude posts in the blog view modal
- * @property {boolean} [includeFiltered] - Whether to include filtered posts
+ * @property {string} [excludeClass] Classname to exclude and add
+ * @property {Function|Function[]} [timeline] Filter results to matching timeline element children
+ * @property {boolean} [noBlogView] Whether to exclude posts in the blog view modal
+ * @property {boolean} [includeFiltered] Whether to include filtered posts
  */
 
 /**
- * @param {Element[]} postElements - Post elements (or descendants) to filter
- * @param {PostFilterOptions} [postFilterOptions] - Post filter options
+ * @param {Element[]} postElements Post elements (or descendants) to filter
+ * @param {PostFilterOptions} [postFilterOptions] Post filter options
  * @returns {HTMLDivElement[]} Matching post elements
  */
 export const filterPostElements = function (postElements, { excludeClass, timeline, noBlogView = false, includeFiltered = false } = {}) {
@@ -82,23 +82,23 @@ export const filterPostElements = function (postElements, { excludeClass, timeli
 };
 
 /**
- * @param {PostFilterOptions} postFilterOptions - Post filter options
+ * @param {PostFilterOptions} postFilterOptions Post filter options
  * @returns {HTMLDivElement[]} Matching post elements on the page
  */
 export const getPostElements = postFilterOptions => filterPostElements([...document.querySelectorAll(postSelector)], postFilterOptions);
 
 /**
- * @param {string} [css] - CSS rules to be included
+ * @param {string} [css] CSS rules to be included
  * @returns {HTMLStyleElement} Style element containing the provided CSS
  */
 export const buildStyle = (css = '') => dom('style', { class: 'xkit' }, null, [css]);
 
 /**
  * Determine a post's legacy type
- * @param {object} post - Destructured into content and layout
- * @param {Array} [post.trail] - Full post trail
- * @param {Array} [post.content] - Post content array
- * @param {Array} [post.layout] - Post layout array
+ * @param {object} post Destructured into content and layout
+ * @param {Array} [post.trail] Full post trail
+ * @param {Array} [post.content] Post content array
+ * @param {Array} [post.layout] Post layout array
  * @returns {string} The determined legacy type of the post
  * @see https://github.com/tumblr/docs/blob/master/npf-spec.md#mapping-npf-post-content-to-legacy-post-types
  */

src/utils/language_data.js

@@ -3,7 +3,7 @@ import { inject } from './inject.js';
 export const languageData = await inject('/main_world/language_data.js');
 
 /**
- * @param {string} rootString - The English string to translate
- * @returns {string} - The translated string in the current Tumblr locale
+ * @param {string} rootString The English string to translate
+ * @returns {string} The translated string in the current Tumblr locale
  */
 export const translate = rootString => languageData.translations[rootString] || rootString;

src/utils/meatballs.js

@@ -15,11 +15,11 @@ const meatballItems = {
 
 /**
  * Add a custom button to posts' meatball menus.
- * @param {object} options - Destructured
- * @param {string} options.id - Identifier for this button (must be unique)
- * @param {string|Function} options.label - Button text to display. May be a function accepting the timelineObject data of the post element being actioned on.
- * @param {Function} options.onclick - Button click listener function
- * @param {Function} [options.postFilter] - Filter function, called with the timelineObject data of the post element being actioned on. Must return true for button to be added
+ * @param {object} options Destructured
+ * @param {string} options.id Identifier for this button (must be unique)
+ * @param {string|Function} options.label Button text to display. May be a function accepting the timelineObject data of the post element being actioned on.
+ * @param {Function} options.onclick Button click listener function
+ * @param {Function} [options.postFilter] Filter function, called with the timelineObject data of the post element being actioned on. Must return true for button to be added
  */
 export const registerMeatballItem = function ({ id, label, onclick, postFilter }) {
   meatballItems.post[id] = { label, onclick, filter: postFilter };
@@ -33,11 +33,11 @@ export const unregisterMeatballItem = id => {
 
 /**
  * Add a custom button to blogs' meatball menus in blog cards and the blog view header.
- * @param {object} options - Destructured
- * @param {string} options.id - Identifier for this button (must be unique)
- * @param {string|Function} options.label - Button text to display. May be a function accepting the blog data of the post element being actioned on.
- * @param {Function} options.onclick - Button click listener function
- * @param {Function} [options.blogFilter] - Filter function, called with the blog data of the menu element being actioned on. Must return true for button to be added. Some blog data fields, such as "followed", are not available in blog cards.
+ * @param {object} options Destructured
+ * @param {string} options.id Identifier for this button (must be unique)
+ * @param {string|Function} options.label Button text to display. May be a function accepting the blog data of the post element being actioned on.
+ * @param {Function} options.onclick Button click listener function
+ * @param {Function} [options.blogFilter] Filter function, called with the blog data of the menu element being actioned on. Must return true for button to be added. Some blog data fields, such as "followed", are not available in blog cards.
  */
 export const registerBlogMeatballItem = function ({ id, label, onclick, blogFilter }) {
   meatballItems.blog[id] = { label, onclick, filter: blogFilter };