Updated plan and added DocComment ESLint rules

.eslintrc.cjs

@@ -1,46 +1,119 @@
 /* eslint-env node */
 'use strict'
 const { defineConfig } = require('@sixxgate/lint')
+const { memo } = require('radash')
 
 module.exports = defineConfig(({ useVue, useNode, useTypeScript }) => {
   useVue({ version: '3.4', style: 'sass' })
   useNode()
   useTypeScript()
 
+  /** @type {() => Partial<import('eslint').Linter.RulesRecord>} */
+  const useCommonJsDocRules = memo(() => ({
+    // Only require the parameters if we want them.
+    'jsdoc/require-param': ['error', { ignoreWhenAllParamsMissing: true }],
+    // Don't require all sections to be filled out.
+    'jsdoc/require-returns': 'off',
+    'jsdoc/require-yields': 'off',
+    // Requires too much configuration to worry about.
+    'jsdoc/tag-lines': 'off',
+    // Don't require DocComments.
+    'jsdoc/require-jsdoc': 'off'
+  }))
+
+  /** @type {() => Partial<import('eslint').Linter.RulesRecord>} */
+  const useJsDocRules = memo(() => ({
+    ...useCommonJsDocRules()
+  }))
+
+  /** @type {() => Partial<import('eslint').Linter.RulesRecord>} */
+  const useTsDocRules = memo(() => ({
+    ...useCommonJsDocRules(),
+    // Only require the parameters if we want them.
+    'jsdoc/require-param': [
+      'error',
+      {
+        ignoreWhenAllParamsMissing: true,
+        // Has issues with TSDoc
+        checkDestructuredRoots: false
+      }
+    ],
+    // Has issues with JSDOc.
+    'jsdoc/check-param-names': ['error', { checkDestructured: false }],
+    // TSDoc itself.
+    'tsdoc/syntax': 'error'
+  }))
+
   return {
     root: true,
     env: { es2023: true },
+    plugins: ['eslint-plugin-tsdoc'],
     reportUnusedDisableDirectives: true,
     overrides: [
+      // CommonJS JavaScript
       {
         files: ['*.cjs'],
+        extends: ['plugin:jsdoc/recommended-error'],
         rules: {
-          '@typescript-eslint/no-require-imports': 'off'
+          '@typescript-eslint/no-require-imports': 'off',
+          ...useJsDocRules()
         },
         parserOptions: {
           project: './tsconfig.config.json'
         }
       },
+      // Main and preload
       {
         files: ['src/core/**/*.ts', 'src/main/**/*.ts', 'src/main/**/*.js', 'src/preload/**/*.ts'],
         parserOptions: {
           project: './tsconfig.node.json'
         }
       },
+      // Main and preload TypeScript
+      {
+        files: ['src/core/**/*.ts', 'src/main/**/*.ts', 'src/preload/**/*.ts'],
+        extends: ['plugin:jsdoc/recommended-typescript-error'],
+        rules: { ...useTsDocRules() }
+      },
+      // Main and preload JavaScript
+      {
+        files: ['src/main/**/*.js'],
+        extends: ['plugin:jsdoc/recommended-error'],
+        rules: { ...useJsDocRules() }
+      },
+      // Renderer
       {
         files: ['src/renderer/**/*.ts', 'src/renderer/**/*.tsx', 'src/renderer/**/*.js', 'src/renderer/**/*.vue'],
         parserOptions: {
           project: './tsconfig.web.json'
         }
       },
+      // Renderer TypeScript
+      {
+        files: ['src/renderer/**/*.ts', 'src/renderer/**/*.tsx', 'src/renderer/**/*.vue'],
+        extends: ['plugin:jsdoc/recommended-typescript-error'],
+        rules: { ...useTsDocRules() }
+      },
+      // Renderer JavaScript
+      {
+        files: ['src/renderer/**/*.js'],
+        extends: ['plugin:jsdoc/recommended-error'],
+        rules: { ...useJsDocRules() }
+      },
+      // Vite configuration
       {
         files: ['electron.vite.config.ts', 'vite.config.ts'],
+        extends: ['plugin:jsdoc/recommended-typescript-error'],
+        rules: { ...useTsDocRules() },
         parserOptions: {
           project: './tsconfig.config.json'
         }
       },
+      // Tests
       {
         files: ['src/tests/**/*.ts'],
+        extends: ['plugin:jsdoc/recommended-typescript-error'],
+        rules: { ...useTsDocRules() },
         parserOptions: {
           project: './tsconfig.test.json'
         }

PLAN.md

@@ -1,7 +1,4 @@
 - Milestones
-  - v2.2
-    - Move more modules to core.
-    - (#74) Rearrangeable dashboard icons.
   - v2.3
     - Determine which drivers are being using by the public at large to remove the experimental mark; options:
       - Add a opt-in telemetry feature to see which drivers are being used, should be an ask to send survey sort of thing.

package.json

@@ -102,9 +102,11 @@
     "eslint-import-resolver-node": "^0.3.9",
     "eslint-import-resolver-typescript": "^3.6.3",
     "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-jsdoc": "^50.6.0",
     "eslint-plugin-n": "^17.14.0",
     "eslint-plugin-prettier": "^5.2.1",
     "eslint-plugin-promise": "^7.2.0",
+    "eslint-plugin-tsdoc": "^0.4.0",
     "eslint-plugin-vue": "^9.31.0",
     "execa": "^9.5.1",
     "husky": "^9.1.7",

src/core/location.ts

@@ -67,26 +67,26 @@ export const hostSchema = z.string().refine(isHost)
 // #endregion
 
 /**
-  Is it a valid hostname?
-
-  From RFC-952 (with relaxation stated in RFC-1123 2.1)
-
-  ```
-  Hostname is <hname>
-  <hname> = <name>*["."<name>]
-  <name> = <let-or-digit>[*[<let-or-digit-or-hyphen]<let-or-digit]
-  ```
-
-  So, the regular expression would be,
-
-  ```
-  <name> = /[\p{N}\p{L}](?:[\p{N}\p{L}-]*[\p{N}\p{L}])?/gu
-  <hname> /^<name>(?:\.<name>)*$/gu
-  ```
-
-  Fully rendered in hostNamePattern, with non-capture groups
-  to capturing converted for better readability.
-*/
+ * Is it a valid hostname?
+ *
+ * From RFC-952 (with relaxation stated in RFC-1123 2.1)
+ *
+ * ```
+ * Hostname is <hname>
+ * <hname> = <name>*["."<name>]
+ * <name> = <let-or-digit>[*[<let-or-digit-or-hyphen]<let-or-digit]
+ * ```
+ *
+ * So, the regular expression would be,
+ *
+ * ```
+ * <name> = /[\p{N}\p{L}](?:[\p{N}\p{L}-]*[\p{N}\p{L}])?/gu
+ * <hname> /^<name>(?:\.<name>)*$/gu
+ * ```
+ *
+ * Fully rendered in hostNamePattern, with non-capture groups
+ * to capturing converted for better readability.
+ */
 const hostNamePattern = /^[\p{N}\p{L}]([\p{N}\p{L}-]*[\p{N}\p{L}])?(\.[\p{N}\p{L}]([\p{N}\p{L}-]*[\p{N}\p{L}])?)*$/u
 /** Determines whether a string is a hostname. */
 export const isHostName = (value: string) => hostNamePattern.test(value)
@@ -95,15 +95,15 @@ export const hostNameSchema = z.string().regex(hostNamePattern)
 // #region IPv4
 
 /**
-  Zod's IP pattern allows some invalid address strings, such as double-zero, `00`.
-  These days IPv4 is generally always in decimal, not octal. It seems Zod was
-  aiming for this. With this in mind, the definition is as follows.
-
-  ```
-  <address> = <octet> 3 * ("." <octet>)
-  <octet> = /(25[0-5])|(2[0-4][0-9])|(1[0-9]{2})|([1-9][0-9])|[0-9]/ # 0 - 255
-  ```
-*/
+ * Zod's IP pattern allows some invalid address strings, such as double-zero, `00`.
+ * These days IPv4 is generally always in decimal, not octal. It seems Zod was
+ * aiming for this. With this in mind, the definition is as follows.
+ *
+ * ```
+ * <address> = <octet> 3 * ("." <octet>)
+ * <octet> = /(25[0-5])|(2[0-4][0-9])|(1[0-9]{2})|([1-9][0-9])|[0-9]/ # 0 - 255
+ * ```
+ */
 const ipV4Pattern =
   /^((25[0-5])|(2[0-4][0-9])|(1[0-9]{2})|([1-9][0-9])|[0-9])(\.((25[0-5])|(2[0-4][0-9])|(1[0-9]{2})|([1-9][0-9])|[0-9])){3}$/u
 /** Determines whether a string is an IPv4 address */
@@ -116,46 +116,46 @@ export const ipV4AddressSchema = z.string().regex(ipV4Pattern)
 // #region IPv6
 
 /**
-  Zod's IPv6 pattern allows a lot of invalid and misses some valid addresses.
-  See {@link https://github.com/colinhacks/zod/issues/2339}.
-  The RFCs seems indicate the following pattern.
-
-  IPv6
-
-  ```
-    <six-address> | <four-address>
-
-    <six-address> = <full-address> | <compact-address>
-    <four-address> = <full-address-prefix> <four-address> | <compact-address-prefix> <four-address>
-
-    <full-address> = <ip6-octet-pair> (7 * (":" <ip6-octet-pair>))
-    <compact-address> = "::" # Zero address
-                      | ":" 7 * (":" <ip6-octet-pair>)
-                      | <ip6-octet-pair> ":" 1-6 * (":" <ip6-octet-pair>)
-                      | 1-2 * (<ip6-octet-pair> ":") 1-5 * (":" <ip6-octet-pair>)
-                      | 1-3 * (<ip6-octet-pair> ":") 1-4 * (":" <ip6-octet-pair>)
-                      | 1-4 * (<ip6-octet-pair> ":") 1-3 * (":" <ip6-octet-pair>)
-                      | 1-5 * (<ip6-octet-pair> ":") 1-2 * (":" <ip6-octet-pair>)
-                      | 1-6 * (<ip6-octet-pair> ":") ":" <ip6-octet-pair>
-                      | 7 * (<ip6-octet-pair> ":") ":"
-
-    <ip6-octet-pair> = /[0-9A-Fa-f]{1,3}/ | /[0-9A-F]{1,3}/i | /[0-9a-f]{1,3}/i
-
-    <full-address-prefix> = <ip6-octet-pair> (5 * (":" <ip6-octet-pair>))
-
-    <compact-address-prefix> = "::" # Zero prefix
-                                 | ":" 5 * (":" <ip6-octet-pair>) ":"
-                                 | <ip6-octet-pair> ":" 1-4 * (":" <ip6-octet-pair>) ":"
-                                 | 1-2 * (<ip6-octet-pair> ":") 1-3 * (":" <ip6-octet-pair>) ":"
-                                 | 1-3 * (<ip6-octet-pair> ":") 1-2 * (":" <ip6-octet-pair>) ":"
-                                 | 1-4 * (<ip6-octet-pair> ":") ":" <ip6-octet-pair> ":"
-                                 | 5 * (<ip6-octet-pair> ":") ":"
-
-    <four-address> = <ip4-octet> (3 * ("." <ip4-octet>))
-
-    <ip4-octet> = /(25[0-5])|(2[0-4][0-9])|(1[0-9]{2})|([1-9][0-9])|[0-9]/ # 0 - 255
-  ```
-*/
+ * Zod's IPv6 pattern allows a lot of invalid and misses some valid addresses.
+ * See {@link https://github.com/colinhacks/zod/issues/2339}.
+ * The RFCs seems indicate the following pattern.
+ *
+ * IPv6
+ *
+ * ```
+ *   <six-address> | <four-address>
+ *
+ *   <six-address> = <full-address> | <compact-address>
+ *   <four-address> = <full-address-prefix> <four-address> | <compact-address-prefix> <four-address>
+ *
+ *   <full-address> = <ip6-octet-pair> (7 * (":" <ip6-octet-pair>))
+ *   <compact-address> = "::" # Zero address
+ *                     | ":" 7 * (":" <ip6-octet-pair>)
+ *                     | <ip6-octet-pair> ":" 1-6 * (":" <ip6-octet-pair>)
+ *                     | 1-2 * (<ip6-octet-pair> ":") 1-5 * (":" <ip6-octet-pair>)
+ *                     | 1-3 * (<ip6-octet-pair> ":") 1-4 * (":" <ip6-octet-pair>)
+ *                     | 1-4 * (<ip6-octet-pair> ":") 1-3 * (":" <ip6-octet-pair>)
+ *                     | 1-5 * (<ip6-octet-pair> ":") 1-2 * (":" <ip6-octet-pair>)
+ *                     | 1-6 * (<ip6-octet-pair> ":") ":" <ip6-octet-pair>
+ *                     | 7 * (<ip6-octet-pair> ":") ":"
+ *
+ *   <ip6-octet-pair> = /[0-9A-Fa-f]{1,3}/ | /[0-9A-F]{1,3}/i | /[0-9a-f]{1,3}/i
+ *
+ *   <full-address-prefix> = <ip6-octet-pair> (5 * (":" <ip6-octet-pair>))
+ *
+ *   <compact-address-prefix> = "::" # Zero prefix
+ *                                | ":" 5 * (":" <ip6-octet-pair>) ":"
+ *                                | <ip6-octet-pair> ":" 1-4 * (":" <ip6-octet-pair>) ":"
+ *                                | 1-2 * (<ip6-octet-pair> ":") 1-3 * (":" <ip6-octet-pair>) ":"
+ *                                | 1-3 * (<ip6-octet-pair> ":") 1-2 * (":" <ip6-octet-pair>) ":"
+ *                                | 1-4 * (<ip6-octet-pair> ":") ":" <ip6-octet-pair> ":"
+ *                                | 5 * (<ip6-octet-pair> ":") ":"
+ *
+ *   <four-address> = <ip4-octet> (3 * ("." <ip4-octet>))
+ *
+ *   <ip4-octet> = /(25[0-5])|(2[0-4][0-9])|(1[0-9]{2})|([1-9][0-9])|[0-9]/ # 0 - 255
+ * ```
+ */
 const ipPairPattern = /^[0-9A-Fa-f]{1,4}$/u
 
 function parsePossibleIpString(value: string) {

src/main/services/level.js

@@ -7,6 +7,8 @@ import levelUp from 'levelup'
 import LevelPouch from 'pouchdb-adapter-leveldb-core'
 import { memo } from 'radash'
 
+/* globals PouchDB */ // Fixes PouchDB undefined in JSDoc.
+
 //
 // NOTE: While PouchDB has a built-in LevelDB adapter, we want to have
 // as minimum of an external footprint as possible. This will be
@@ -21,7 +23,7 @@ import { memo } from 'radash'
 export const useLevelDb = memo(function useLevelDb() {
   const leveldown = memo(
     /**
-     * @param {string} name
+     * @param {string} name The name of the database.
      */
     function leveldown(name) {
       const path = resolvePath(app.getPath('userData'), name)
@@ -39,18 +41,20 @@ export const useLevelDb = memo(function useLevelDb() {
 
   const levelup = memo(
     /**
-     * @param {string} name
+     * @param {string} name The name of the database.
      */
     async function levelup(name) {
       const db = leveldown(name)
       return await new Promise(
+        /* eslint-disable jsdoc/no-undefined-types -- Has issue with generics. */
         /**
-         * @param {(db: LevelUp<LevelDown>) => void} resolve
-         * @param {(error: Error) => void} reject
+         * @param {(db: LevelUp<LevelDown>) => void} resolve Resolver
+         * @param {(error: Error) => void} reject Rejecter
          */
+        /* eslint-enable jsdoc/no-undefined-types */
         (resolve, reject) => {
           /**
-           * @param {Error|undefined} error
+           * @param {Error|undefined} error Error
            */
           const cb = (error) => {
             /* v8 ignore next 2 */ // No way to spy or mock this deep in.
@@ -77,8 +81,8 @@ export const useLevelAdapter = memo(function useLevelAdapter() {
 
   /**
    * @this {Partial<LevelPouch>}
-   * @param {Record<string, unknown>} opts
-   * @param {ErrorCallback} cb
+   * @param {Record<string, unknown>} opts Plugin options
+   * @param {ErrorCallback} cb Error callback
    */
   function MainDown(opts, cb) {
     // eslint-disable-next-line -- Everything is messed up with no typings.

src/renderer/services/driver.ts

@@ -31,9 +31,9 @@ export interface Driver extends DriverInformation {
   /**
    * Sets input and output ties.
    *
-   * @param input The input channel to tie.
-   * @param videoOutput The output video channel to tie.
-   * @param audioOutput The output audio channel to tie.
+   * @param input - The input channel to tie.
+   * @param videoOutput - The output video channel to tie.
+   * @param audioOutput - The output audio channel to tie.
    */
   readonly activate: (input: number, videoOutput: number, audioOutput: number) => Promise<void>
   /** Powers on the switch or monitor. */