chore: use function signatures in JSDoc where trivial

src/utils/dom.js

@@ -1,5 +1,5 @@
 /** @typedef {Record<string, string>} Attributes */
-/** @typedef {Record<string, () => void>} Events */
+/** @typedef {Record<string, (event: Event) => void>} Events */
 /** @typedef {(string | Node)[]} Children */
 
 /**

src/utils/interface.js

@@ -37,10 +37,12 @@ export const getPopoverWrapper = element => {
     : closestWrapper;
 };
 
+/** @typedef {(timeline: HTMLElement) => boolean} TimelineFilter */
+
 /**
- * @typedef {object} PostFilterOptions
+ * @typedef PostFilterOptions
  * @property {string} [excludeClass] Classname to exclude and add
- * @property {Function|Function[]} [timeline] Filter results to matching timeline element children
+ * @property {TimelineFilter | TimelineFilter[]} [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
  */

src/utils/meatballs.js

@@ -16,8 +16,8 @@ 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 {string | Function} options.label Button text to display. May be a function accepting the timelineObject data of the post element being actioned on.
+ * @param {(event: PointerEvent) => void} 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 }) {
@@ -34,8 +34,8 @@ 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 {string | Function} options.label Button text to display. May be a function accepting the blog data of the post element being actioned on.
+ * @param {(event: PointerEvent) => void} 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 }) {

src/utils/mutations.js

@@ -1,5 +1,6 @@
 import { keyToCss } from './css_map.js';
 import { notificationSelector, postSelector } from './interface.js';
+
 const rootNode = document.getElementById('root');
 const headNode = document.querySelector('head');
 
@@ -16,12 +17,12 @@ const isolateErrors = callback => {
 };
 
 export const pageModifications = Object.freeze({
-  listeners: new Map(),
+  /** @type {Map<(elements: Element[]) => void, string>} */ listeners: new Map(),
 
   /**
    * Register a page modification
    * @param {string} selector CSS selector for elements to target
-   * @param {Function} modifierFunction Function to handle matching elements (accepts one Element[] argument)
+   * @param {(elements: Element[]) => void} modifierFunction Function to handle matching elements
    */
   register (selector, modifierFunction) {
     if (this.listeners.has(modifierFunction) === false) {
@@ -32,15 +33,15 @@ export const pageModifications = Object.freeze({
 
   /**
    * Unregister a page modification
-   * @param {Function} modifierFunction Previously-registered function to remove
+   * @param {(elements: Element[]) => void} modifierFunction Previously-registered function to remove
    */
   unregister (modifierFunction) {
     this.listeners.delete(modifierFunction);
   },
 
   /**
    * Run a page modification on all existing matching elements
-   * @param {Function} modifierFunction Previously-registered function to run
+   * @param {(elements: Element[]) => void} modifierFunction Previously-registered function to run
    */
   trigger (modifierFunction) {
     const selector = this.listeners.get(modifierFunction);

src/utils/post_actions.js

@@ -29,7 +29,7 @@ pageModifications.register(keyToCss('postFormButton'), addPostOptions);
  * @param {string} id Unique identifier for this post option
  * @param {object} options Construction options for this post option
  * @param {string} options.symbolId RemixIcon symbol to use
- * @param {Function} options.onclick Click handler function for this button
+ * @param {(event: PointerEvent) => void} options.onclick Click handler function for this button
  */
 export const registerPostOption = async function (id, { symbolId, onclick }) {
   postOptions[id] = dom('label', { class: 'xkit-post-option', [displayBlockUnlessDisabledAttr]: '' }, null, [

src/utils/sidebar.js

@@ -23,7 +23,7 @@ const carrotSvg = dom('svg', {
 /**
  * @typedef {object} sidebarRowOptions
  * @property {string} label Human-readable link text
- * @property {Function} onclick Click event handler for this row
+ * @property {(event: PointerEvent) => void} onclick Click event handler for this row
  * @property {string} [href] Optional link URL for this row
  * @property {string} [count] Human-readable additional link text
  * @property {boolean} [carrot] Whether to include a right-facing arrow on the link (ignored if count is specified)