ESlint JSdoc (#2148)

* Install eslint-plugin-jsdoc

* Initial rules setup

* Update lists

* Use @returns rather than @return

* Remove error throwing code which is never executed

* Fix issues relating to @throws

* General error fixes

* Update Display type documentation

* Various doc fixes

* Fix invalid tuple syntax

* Doc updates

* Remove unused

* Doc updates

* Enable jsdoc/require-returns

* Update rules

* Update remaining rules

1 files changed, 118 insertions, 0 deletions

diff --git a/package-lock.json b/package-lock.json
index a09eb187..b7b5cda1 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -15,6 +15,7 @@
                 "css": "^3.0.0",
                 "eslint": "^8.15.0",
                 "eslint-plugin-header": "^3.1.1",
+                "eslint-plugin-jsdoc": "^39.2.9",
                 "eslint-plugin-no-unsanitized": "^4.0.1",
                 "fake-indexeddb": "^3.1.7",
                 "html-validate": "^7.1.0",
@@ -197,6 +198,20 @@
             "integrity": "sha1-VgiurfwAvmwpAd9fmGF4jeDVl8g=",
             "dev": true
         },
+        "node_modules/@es-joy/jsdoccomment": {
+            "version": "0.29.0",
+            "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.29.0.tgz",
+            "integrity": "sha512-4yKy5t+/joLihG+ei6CCU6sc08sjUdEdXCQ2U+9h9VP13EiqHQ4YMgDC18ys/AsLdJDBX3KRx/AWY6PR7hn52Q==",
+            "dev": true,
+            "dependencies": {
+                "comment-parser": "1.3.1",
+                "esquery": "^1.4.0",
+                "jsdoc-type-pratt-parser": "~3.0.1"
+            },
+            "engines": {
+                "node": "^14 || ^16 || ^17 || ^18"
+            }
+        },
         "node_modules/@eslint/eslintrc": {
             "version": "1.2.3",
             "resolved": "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-1.2.3.tgz",
@@ -1801,6 +1816,15 @@
             "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==",
             "dev": true
         },
+        "node_modules/comment-parser": {
+            "version": "1.3.1",
+            "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.3.1.tgz",
+            "integrity": "sha512-B52sN2VNghyq5ofvUsqZjmk6YkihBX5vMSChmSK9v4ShjKf3Vk5Xcmgpw4o+iIgtrnM/u5FiMpz9VKb8lpBveA==",
+            "dev": true,
+            "engines": {
+                "node": ">= 12.0.0"
+            }
+        },
         "node_modules/common-tags": {
             "version": "1.8.2",
             "resolved": "https://registry.npmjs.org/common-tags/-/common-tags-1.8.2.tgz",
@@ -3145,6 +3169,42 @@
                 "eslint": ">=7.7.0"
             }
         },
+        "node_modules/eslint-plugin-jsdoc": {
+            "version": "39.2.9",
+            "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-39.2.9.tgz",
+            "integrity": "sha512-gaPYJT94rWlWyQcisQyyEJHtLaaJqN4baFlLCEr/LcXVibS9wzQTL2dskqk327ggwqQopR+Xecu2Lng1IJ9Ypw==",
+            "dev": true,
+            "dependencies": {
+                "@es-joy/jsdoccomment": "~0.29.0",
+                "comment-parser": "1.3.1",
+                "debug": "^4.3.4",
+                "escape-string-regexp": "^4.0.0",
+                "esquery": "^1.4.0",
+                "semver": "^7.3.7",
+                "spdx-expression-parse": "^3.0.1"
+            },
+            "engines": {
+                "node": "^14 || ^16 || ^17 || ^18"
+            },
+            "peerDependencies": {
+                "eslint": "^7.0.0 || ^8.0.0"
+            }
+        },
+        "node_modules/eslint-plugin-jsdoc/node_modules/semver": {
+            "version": "7.3.7",
+            "resolved": "https://registry.npmjs.org/semver/-/semver-7.3.7.tgz",
+            "integrity": "sha512-QlYTucUYOews+WeEujDoEGziz4K6c47V/Bd+LjSSYcA94p+DmINdf7ncaUinThfvZyu13lN9OY1XDxt8C0Tw0g==",
+            "dev": true,
+            "dependencies": {
+                "lru-cache": "^6.0.0"
+            },
+            "bin": {
+                "semver": "bin/semver.js"
+            },
+            "engines": {
+                "node": ">=10"
+            }
+        },
         "node_modules/eslint-plugin-no-unsanitized": {
             "version": "4.0.1",
             "resolved": "https://registry.npmjs.org/eslint-plugin-no-unsanitized/-/eslint-plugin-no-unsanitized-4.0.1.tgz",
@@ -5404,6 +5464,15 @@
             "integrity": "sha1-peZUwuWi3rXyAdls77yoDA7y9RM=",
             "dev": true
         },
+        "node_modules/jsdoc-type-pratt-parser": {
+            "version": "3.0.1",
+            "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-3.0.1.tgz",
+            "integrity": "sha512-vqMCdAFVIiFhVgBYE/X8naf3L/7qiJsaYWTfUJZZZ124dR3OUz9HrmaMUGpYIYAN4VSuodf6gIZY0e8ktPw9cg==",
+            "dev": true,
+            "engines": {
+                "node": ">=12.0.0"
+            }
+        },
         "node_modules/jsdom": {
             "version": "19.0.0",
             "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-19.0.0.tgz",
@@ -10348,6 +10417,17 @@
                 "async": "~0.2.9"
             }
         },
+        "@es-joy/jsdoccomment": {
+            "version": "0.29.0",
+            "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.29.0.tgz",
+            "integrity": "sha512-4yKy5t+/joLihG+ei6CCU6sc08sjUdEdXCQ2U+9h9VP13EiqHQ4YMgDC18ys/AsLdJDBX3KRx/AWY6PR7hn52Q==",
+            "dev": true,
+            "requires": {
+                "comment-parser": "1.3.1",
+                "esquery": "^1.4.0",
+                "jsdoc-type-pratt-parser": "~3.0.1"
+            }
+        },
         "@eslint/eslintrc": {
             "version": "1.2.3",
             "resolved": "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-1.2.3.tgz",
@@ -11683,6 +11763,12 @@
             "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==",
             "dev": true
         },
+        "comment-parser": {
+            "version": "1.3.1",
+            "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.3.1.tgz",
+            "integrity": "sha512-B52sN2VNghyq5ofvUsqZjmk6YkihBX5vMSChmSK9v4ShjKf3Vk5Xcmgpw4o+iIgtrnM/u5FiMpz9VKb8lpBveA==",
+            "dev": true
+        },
         "common-tags": {
             "version": "1.8.2",
             "resolved": "https://registry.npmjs.org/common-tags/-/common-tags-1.8.2.tgz",
@@ -12810,6 +12896,32 @@
             "dev": true,
             "requires": {}
         },
+        "eslint-plugin-jsdoc": {
+            "version": "39.2.9",
+            "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-39.2.9.tgz",
+            "integrity": "sha512-gaPYJT94rWlWyQcisQyyEJHtLaaJqN4baFlLCEr/LcXVibS9wzQTL2dskqk327ggwqQopR+Xecu2Lng1IJ9Ypw==",
+            "dev": true,
+            "requires": {
+                "@es-joy/jsdoccomment": "~0.29.0",
+                "comment-parser": "1.3.1",
+                "debug": "^4.3.4",
+                "escape-string-regexp": "^4.0.0",
+                "esquery": "^1.4.0",
+                "semver": "^7.3.7",
+                "spdx-expression-parse": "^3.0.1"
+            },
+            "dependencies": {
+                "semver": {
+                    "version": "7.3.7",
+                    "resolved": "https://registry.npmjs.org/semver/-/semver-7.3.7.tgz",
+                    "integrity": "sha512-QlYTucUYOews+WeEujDoEGziz4K6c47V/Bd+LjSSYcA94p+DmINdf7ncaUinThfvZyu13lN9OY1XDxt8C0Tw0g==",
+                    "dev": true,
+                    "requires": {
+                        "lru-cache": "^6.0.0"
+                    }
+                }
+            }
+        },
         "eslint-plugin-no-unsanitized": {
             "version": "4.0.1",
             "resolved": "https://registry.npmjs.org/eslint-plugin-no-unsanitized/-/eslint-plugin-no-unsanitized-4.0.1.tgz",
@@ -14501,6 +14613,12 @@
             "integrity": "sha1-peZUwuWi3rXyAdls77yoDA7y9RM=",
             "dev": true
         },
+        "jsdoc-type-pratt-parser": {
+            "version": "3.0.1",
+            "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-3.0.1.tgz",
+            "integrity": "sha512-vqMCdAFVIiFhVgBYE/X8naf3L/7qiJsaYWTfUJZZZ124dR3OUz9HrmaMUGpYIYAN4VSuodf6gIZY0e8ktPw9cg==",
+            "dev": true
+        },
         "jsdom": {
             "version": "19.0.0",
             "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-19.0.0.tgz",