chore: add eslint-plugin-jsdoc and improve documentation

Author: KristjanESPERANTO

MMM-Remote-Control.js

@@ -167,7 +167,7 @@ Module.register("MMM-Remote-Control", {
 
   /**
    * Handle DEFAULT_SETTINGS notification - manage module visibility
-   * @param {Object} payload - Settings data
+   * @param {object} payload - Settings data
    */
   handleDefaultSettings (payload) {
     let {settingsVersion} = payload;
@@ -208,7 +208,7 @@ Module.register("MMM-Remote-Control", {
   /**
    * Handle HIDE/SHOW/TOGGLE notifications - manage module visibility
    * @param {string} notification - Type of visibility action
-   * @param {Object} payload - Notification data with module info
+   * @param {object} payload - Notification data with module info
    */
   handleModuleVisibility (notification, payload) {
     const options = {lockString: this.identifier};

eslint.config.mjs

@@ -5,6 +5,7 @@ import {flatConfigs as importX} from "eslint-plugin-import-x";
 import js from "@eslint/js";
 import json from "@eslint/json";
 import markdown from "@eslint/markdown";
+import pluginJsdoc from "eslint-plugin-jsdoc";
 import stylistic from "@stylistic/eslint-plugin";
 import unicorn from "eslint-plugin-unicorn";
 
@@ -22,8 +23,8 @@ export default defineConfig([
         "$node": "writable"
       }
     },
-    "plugins": {js, stylistic},
-    "extends": [importX.recommended, "js/recommended", "stylistic/all", unicorn.configs.recommended],
+    "plugins": {js, "jsdoc": pluginJsdoc, stylistic},
+    "extends": [importX.recommended, pluginJsdoc.configs["flat/recommended"], "js/recommended", "stylistic/all", unicorn.configs.recommended],
     "rules": {
       "@stylistic/array-element-newline": ["error", "consistent"],
       "@stylistic/brace-style": ["error", "1tbs", {"allowSingleLine": true}],
@@ -51,6 +52,12 @@ export default defineConfig([
       "unicorn/switch-case-braces": ["error", "avoid"]
     }
   },
+  {
+    "files": ["**/*.test.js"],
+    "rules": {
+      "jsdoc/require-jsdoc": "off"
+    }
+  },
   {
     "files": ["**/*.mjs"],
     "languageOptions": {

lib/configUtils.js

@@ -2,12 +2,12 @@
  * cleanConfig removes keys from the full MagicMirror config object that equal their defaults.
  * It mirrors the logic inside removeDefaultValues in node_helper.js but is pure and testable.
  * Mutates and also returns the provided config object.
- *
- * @param {object} params
+ * @param {object} params - Configuration cleaning parameters
  * @param {object} params.config - The full runtime config (will be mutated)
  * @param {object} params.defaultConfig - Global MagicMirror default config
- * @param {Object.<string,object>} params.moduleDefaultsMap - Map moduleName -> defaults
+ * @param {Record<string, object>} params.moduleDefaultsMap - Map moduleName -> defaults
  * @param {Array<object>} [params.moduleDataFromBrowser] - Optional list providing defaults for bundled modules
+ * @returns {object} The cleaned config object (same reference as input)
  */
 function cleanConfig ({config, defaultConfig, moduleDefaultsMap, moduleDataFromBrowser = []}) {
   if (!config || typeof config !== "object") return config;

lib/utils.js

@@ -3,17 +3,33 @@
  * Pure functions – no side effects.
  */
 
+/**
+ * Capitalizes the first character of a string.
+ * @param {string} string - The string to capitalize
+ * @returns {string} String with first character capitalized
+ */
 function capitalizeFirst (string) {
   if (!string) return string;
   return string.charAt(0).toUpperCase() + string.slice(1);
 }
 
+/**
+ * Formats a module name by removing MMM- prefix and converting to title case.
+ * @param {string} string - The module name to format
+ * @returns {string} Formatted module name with spaces and title case
+ */
 function formatName (string) {
   if (!string) return string;
   // Original logic: strip MMM-, split camelCase, convert delimiters to spaces & capitalize
   return string.replaceAll("MMM-", "").replaceAll(/([a-z])([A-Z])/g, "$1 $2").replaceAll(/(^|[-_])(\w)/g, ($0, $1, $2) => ($1 && " ") + $2.toUpperCase());
 }
 
+/**
+ * Checks if a string contains a pattern (null-safe).
+ * @param {string} pattern - The pattern to search for
+ * @param {string} string - The string to search in
+ * @returns {boolean} True if pattern is found in string
+ */
 function includes (pattern, string) {
   if (string == undefined) return false;
   return string.includes(pattern);

node_helper.js

@@ -817,10 +817,10 @@ module.exports = NodeHelper.create({
   /**
    * Sends custom notification to MagicMirror modules.
    * Attempts to parse JSON string payloads, falls back to raw string on error.
-   * @param {Object} query - Query with notification name and optional payload
+   * @param {object} query - Query with notification name and optional payload
    * @param {string} query.notification - Notification name to broadcast
-   * @param {*} query.payload - Payload (object, JSON string, or primitive)
-   * @param {Object} res - Express response object
+   * @param {object|string|number|boolean|null} query.payload - Payload (object, JSON string, or primitive)
+   * @param {object} res - Express response object
    * @returns {boolean} Always true (errors are handled internally)
    */
   handleNotification (query, res) {
@@ -928,8 +928,8 @@ module.exports = NodeHelper.create({
   /**
    * Forwards action to frontend without validation.
    * Used for SHOW/HIDE/TOGGLE - frontend filters invalid/missing module parameters.
-   * @param {Object} query - Query object containing action and optional module identifier
-   * @param {Object} res - Express response object or socket placeholder
+   * @param {object} query - Query object containing action and optional module identifier
+   * @param {object} res - Express response object or socket placeholder
    */
   handleSimpleSocketNotification (query, res) {
     this.sendSocketNotification(query.action, query);