Replaced "Record." by "Object.", because Record is TypeScript syntax …

…and not valid JSDoc. -- Unfortunately I had to replace the typedef packetItemId, because the JSDoc Object. syntax for records requires type string as index. -- For type compatibility with TypeScript (and TypeScript based tools like VS Code), the keyword Object in JSDoc must be upper case. To prevent such tools reporting false positive errors, the setting of eslint-plugin-jsdoc (this case is described here: https://github.com/gajus/eslint-plugin-jsdoc/blob/master/README.md#why-not-capital-case-everything)
mixxxdj · Oct 9, 2022 · 4ec232f · 4ec232f
1 parent 0478a76
commit 4ec232f
Show file tree

Hide file tree

Showing 2 changed files with 76 additions and 54 deletions.
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -1,63 +1,91 @@
 {
-  "extends": ["eslint:recommended", "plugin:jsdoc/recommended"],
+  "extends": [ "eslint:recommended", "plugin:jsdoc/recommended" ],
   "parserOptions": {
     "ecmaVersion": 7,
     "sourceType": "script"
   },
   "env": {
     "es6": true
   },
-  "plugins": ["jsdoc"],
+  "plugins": [ "jsdoc" ],
+  "settings": {
+    "jsdoc": {
+      "preferredTypes": {
+        "object": "Object"
+      }
+    }
+  },
   "rules": {
-    "array-bracket-spacing" : "warn",
+    "array-bracket-spacing": "warn",
     "block-spacing": "warn",
-    "brace-style": ["warn", "1tbs", {
+    "brace-style": [
+      "warn",
+      "1tbs",
+      {
         "allowSingleLine": true
-    }],
+      }
+    ],
     "curly": "warn",
     "camelcase": "warn",
     "comma-spacing": "warn",
-    "computed-property-spacing" : ["warn", "never", {
+    "computed-property-spacing": [
+      "warn",
+      "never",
+      {
         "enforceForClassMembers": true
-    }],
-    "dot-location": ["warn", "property"],
+      }
+    ],
+    "dot-location": [ "warn", "property" ],
     "dot-notation": "warn",
-    "eqeqeq": ["error", "always"],
+    "eqeqeq": [ "error", "always" ],
     "func-call-spacing": "warn",
-    "func-style": ["error", "expression", {
+    "func-style": [
+      "error",
+      "expression",
+      {
         "allowArrowFunctions": true
-    }],
-    "indent": ["warn", 4],
+      }
+    ],
+    "indent": [ "warn", 4 ],
     "key-spacing": "warn",
     "keyword-spacing": "warn",
-    "linebreak-style": ["warn", "unix"],
+    "linebreak-style": [ "warn", "unix" ],
     "newline-per-chained-call": "warn",
     "no-constructor-return": "warn",
     "no-extra-bind": "warn",
     "no-sequences": "warn",
     "no-useless-call": "warn",
     "no-useless-return": "warn",
     "no-trailing-spaces": "warn",
-    "no-unneeded-ternary": ["warn", {
+    "no-unneeded-ternary": [
+      "warn",
+      {
         "defaultAssignment": false
-    }],
-    "no-unused-vars": ["error", {
+      }
+    ],
+    "no-unused-vars": [
+      "error",
+      {
         "argsIgnorePattern": "^_"
-    }],
+      }
+    ],
     "no-var": "warn",
-    "object-curly-newline" : ["warn", {
+    "object-curly-newline": [
+      "warn",
+      {
         "consistent": true,
         "multiline": true
-    }],
-    "object-curly-spacing" : "warn",
+      }
+    ],
+    "object-curly-spacing": "warn",
     "prefer-const": "warn",
     "prefer-regex-literals": "warn",
-    "quotes": ["warn", "double"],
+    "quotes": [ "warn", "double" ],
     "require-atomic-updates": "error",
     "semi": "warn",
     "semi-spacing": "warn",
-    "space-before-blocks": ["warn", "always"],
-    "space-before-function-paren": ["warn", "never"],
+    "space-before-blocks": [ "warn", "always" ],
+    "space-before-function-paren": [ "warn", "never" ],
     "space-in-parens": "warn",
     "yoda": "warn"
   },
@@ -66,13 +94,13 @@
   },
   "overrides": [
     {
-      "files": ["**/*.mjs"],
+      "files": [ "**/*.mjs" ],
       "parserOptions": {
         "sourceType": "module"
       }
     },
     {
-      "files": ["res/controllers/common-hid-packet-parser.js"],
+      "files": [ "res/controllers/common-hid-packet-parser.js" ],
       "globals": {
         "console": "readonly"
       },
@@ -81,7 +109,7 @@
       }
     },
     {
-      "files": ["res/controllers/*.js"],
+      "files": [ "res/controllers/*.js" ],
       "excludedFiles": "res/controllers/common-hid-packet-parser.js",
       "globals": {
         "console": "readonly",

diff --git a/res/controllers/common-hid-packet-parser.js b/res/controllers/common-hid-packet-parser.js
@@ -18,7 +18,7 @@ this.HIDDebug = function(message) {
  *
  * @callback packetCallback
  * @param {HIDPacket} packet The packet that represents the InputReport
- * @param {Record.<string, packetField | bitObject>} changed_data The data received from the device
+ * @param {Object.<string, packetField | bitObject>} changed_data The data received from the device
  */
 /**
  * Callback function to call when, the value of a modifier control changed
@@ -69,24 +69,17 @@ this.HIDDebug = function(message) {
  * @param {boolean} isScratchEnabled True, when button 'jog_touch' is active
  */
 
-/**
- * A string of group and control name separated by a dot
- *
- * @typedef packetItemId
- * @type {string}
- */
-
 /**
  * @typedef packetField
- * @type {object}
+ * @type {Object}
  * @property {HIDPacket} packet
- * @property {packetItemId} id Group and control name separated by a dot
+ * @property {string} id Group and control name separated by a dot
  * @property {string} group
  * @property {string} name
  * @property {string} mapped_group Mapped group, must be a valid Mixxx control group name e.g. "[Channel1]"
  * @property {string} mapped_name Name of mapped control, must be a valid Mixxx control name "VuMeter"
  * @property {controlCallback} mapped_callback
- * @property {object} pack Control packing format for unpack(), one of b/B, h/H, i/I
+ * @property {Object} pack Control packing format for unpack(), one of b/B, h/H, i/I
  * @property {number} offset
  * @property {number} end_offset
  * @property {number} bitmask
@@ -110,9 +103,9 @@ this.HIDDebug = function(message) {
 
 /**
  * @typedef bitObject
- * @type {object}
+ * @type {Object}
  * @property {HIDPacket} packet
- * @property {packetItemId} id Group and control name separated by a dot
+ * @property {string} id Group and control name separated by a dot
  * @property {string} group
  * @property {string} name
  * @property {string} mapped_group Mapped group, must be a valid Mixxx control group name e.g. "[Channel1]"
@@ -149,7 +142,7 @@ class HIDBitVector {
         /**
          * Object of bitObjects, referred by a string of group and control name separated by a dot
          *
-         * @type {Record.<packetItemId, bitObject>}
+         * @type {Object.<string, bitObject>}
          */
         this.bits = {};
     }
@@ -241,14 +234,14 @@ class HIDModifierList {
         /**
          * Actual value of the modifier
          *
-         * @type {Record.<string, boolean>}
+         * @type {Object.<string, boolean>}
          */
         this.modifiers = Object();
 
         /**
          * Function to be called after modifier value changes
          *
-         * @type {Record.<string, modifierCallback>}
+         * @type {Object.<string, modifierCallback>}
          */
         this.callbacks = Object();
     }
@@ -497,7 +490,7 @@ class HIDPacket {
      * position 0
      *                        - For HID devices which use ReportIDs to enumerate the reports, the
      * data bytes starts at position 1
-     * @param {object} pack Is one of the field packing types:
+     * @param {Object} pack Is one of the field packing types:
      *              - b       signed byte
      *              - B       unsigned byte
      *              - h       signed short
@@ -632,7 +625,7 @@ class HIDPacket {
      * position 0
      *                        - For HID devices which use ReportIDs to enumerate the reports, the
      * data bytes starts at position 1
-     * @param {object} pack Is one of the field packing types:
+     * @param {Object} pack Is one of the field packing types:
      *              - b       signed byte
      *              - B       unsigned byte
      *              - h       signed short
@@ -774,7 +767,7 @@ class HIDPacket {
      * position 0
      *                        - For HID devices which use ReportIDs to enumerate the reports, the
      * data bytes starts at position 1
-     * @param {object} pack Is one of the field packing types:
+     * @param {Object} pack Is one of the field packing types:
      *              - b       signed byte
      *              - B       unsigned byte
      *              - h       signed short
@@ -942,13 +935,14 @@ class HIDPacket {
      * @param {packetField} field Object that describes a field inside of a packet, which can often
      *     mapped to a Mixxx control.
      * @param {number} value Value must be a valid unsigned byte to parse, with enough bits.
-     * @returns {Record.<packetItemId, bitObject>} List of modified bits (delta)
+     * @returns {Object.<string, bitObject>} List of modified bits (delta),
+     *                                       refered by a string of group and control name separated by a dot
      */
     parseBitVector(field, value) {
         /**
          * Object of bitObjects, referred by a string of group and control name separated by a dot
          *
-         * @type {Record.<packetItemId, bitObject>}
+         * @type {Object.<string, bitObject>}
          */
         const bits = {};
 
@@ -973,13 +967,13 @@ class HIDPacket {
      * BitVectors are returned as bits you can iterate separately.
      *
      * @param {Uint8Array} data Data received as InputReport from the device
-     * @returns {Record.<packetItemId, packetField | bitObject>} List of changed fields with new value.
+     * @returns {Object.<string, packetField | bitObject>} List of changed fields with new value.
      */
     parse(data) {
         /**
          * Object of packetField or bitObjects, referred by a string of group and control name separated by a dot
          *
-         * @type {Record.<packetItemId, packetField | bitObject>}
+         * @type {Object.<string, packetField | bitObject>}
          */
         const field_changes = {};
 
@@ -1104,14 +1098,14 @@ class HIDController {
         /**
          * HIDPackets representing HID InputReports, by packet name
          *
-         * @type {Record.<string, HIDPacket>}
+         * @type {Object.<string, HIDPacket>}
          */
         this.InputPackets = {};
 
         /**
          * HIDPackets representing HID OutputReports, by packet name
          *
-         * @type {Record.<string, HIDPacket>}
+         * @type {Object.<string, HIDPacket>}
          */
         this.OutputPackets = {};
 
@@ -1291,14 +1285,14 @@ class HIDController {
         /**
          * Object of scaling function callbacks by name
          *
-         * @type {Record.<string, scalingCallback>}
+         * @type {Object.<string, scalingCallback>}
          */
         this.scalers = {};
 
         /**
          * Object of engine timer IDs, by hid-parser timer IDs
          *
-         * @type {Record.<number, number>}
+         * @type {Object.<number, number>}
          */
         this.timers = {};
 
@@ -1747,7 +1741,7 @@ class HIDController {
      *   fields in default mixxx groups. Not done if a callback was defined.
      *
      * @param {any} packet Unused
-     * @param {Record.<string, packetField | bitObject>} delta
+     * @param {Object.<string, packetField | bitObject>} delta
      */
     processIncomingPacket(packet, delta) {
         /** @type {packetField} */