ESLint: Added JSDoc plugin (#2869)

.eslintrc.js

@@ -1,6 +1,7 @@
 /** @type {import('eslint').Linter.Config} */
 module.exports = {
 	root: true,
+	plugins: ['jsdoc'],
 	extends: 'eslint:recommended',
 	rules: {
 		'no-use-before-define': ['error', { 'functions': false, 'classes': false }],
@@ -13,6 +14,18 @@ module.exports = {
 		'semi': 'warn',
 		'wrap-iife': 'warn',
 
+		// JSDoc
+		'jsdoc/check-alignment': 'warn',
+		'jsdoc/check-syntax': 'warn',
+		'jsdoc/check-param-names': 'warn',
+		'jsdoc/require-hyphen-before-param-description': ['warn', 'never'],
+		'jsdoc/check-tag-names': 'warn',
+		'jsdoc/check-types': 'warn',
+		'jsdoc/empty-tags': 'warn',
+		'jsdoc/newline-after-description': 'warn',
+		'jsdoc/require-param-name': 'warn',
+		'jsdoc/require-property-name': 'warn',
+
 		// I turned this rule off because we use `hasOwnProperty` in a lot of places
 		// TODO: Think about re-enabling this rule
 		'no-prototype-builtins': 'off',
@@ -27,6 +40,9 @@ module.exports = {
 		'no-empty-character-class': 'off',
 		'no-useless-escape': 'off'
 	},
+	settings: {
+		jsdoc: { mode: 'typescript' }
+	},
 	ignorePatterns: [
 		'*.min.js',
 		'vendor/',

components/prism-core.js

@@ -1047,6 +1047,7 @@ function LinkedList() {
 
 /**
  * Adds a new node with the given value to the list.
+ *
  * @param {LinkedList<T>} list
  * @param {LinkedListNode<T>} node
  * @param {T} value
@@ -1066,6 +1067,7 @@ function addAfter(list, node, value) {
 }
 /**
  * Removes `count` nodes after the given node. The given node will not be removed.
+ *
  * @param {LinkedList<T>} list
  * @param {LinkedListNode<T>} node
  * @param {number} count
@@ -1190,7 +1192,7 @@ if (typeof global !== 'undefined') {
  * each another.
  * @global
  * @public
-*/
+ */
 
 /**
  * @typedef Grammar
@@ -1208,7 +1210,7 @@ if (typeof global !== 'undefined') {
  * @returns {void}
  * @global
  * @public
-*/
+ */
 
 /**
  * @callback HookCallback

components/prism-kumir.js

@@ -2,14 +2,16 @@
 
 	/**
 	 * Regular expression for characters that are not allowed in identifiers.
-	 * @type {String}
+	 *
+	 * @type {string}
 	 */
 	var nonId = /\s\x00-\x1f\x22-\x2f\x3a-\x3f\x5b-\x5e\x60\x7b-\x7e/.source;
 
 	/**
 	 * Surround a regular expression for IDs with patterns for non-ID sequences.
-	 * @param {String} pattern A regular expression for identifiers.
+	 *
-	 * @param {String} [flags] The regular expression flags.
+	 * @param {string} pattern A regular expression for identifiers.
+	 * @param {string} [flags] The regular expression flags.
 	 * @returns {RegExp} A wrapped regular expression for identifiers.
 	 */
 	function wrapId(pattern, flags) {

dependencies.js

@@ -232,6 +232,7 @@ var getLoader = (function () {
 
 		/**
 		 * A set of ids of nodes which are not depended upon by any other node in the graph.
+		 *
 		 * @type {StringSet}
 		 */
 		var ends = {};
@@ -261,6 +262,7 @@ var getLoader = (function () {
 
 			/**
 			 * The value to be returned.
+			 *
 			 * @type {T}
 			 */
 			var value;

docs/global.html

@@ -143,7 +143,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="prism-core.js.html">prism-core.js</a>, <a href="prism-core.js.html#line1195">line 1195</a>
+        <a href="prism-core.js.html">prism-core.js</a>, <a href="prism-core.js.html#line1197">line 1197</a>
     </li></ul></dd>
     
 
@@ -274,7 +274,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="prism-core.js.html">prism-core.js</a>, <a href="prism-core.js.html#line1174">line 1174</a>
+        <a href="prism-core.js.html">prism-core.js</a>, <a href="prism-core.js.html#line1176">line 1176</a>
     </li></ul></dd>
     
 
@@ -559,7 +559,7 @@ each another.</p></td>
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="prism-core.js.html">prism-core.js</a>, <a href="prism-core.js.html#line1203">line 1203</a>
+        <a href="prism-core.js.html">prism-core.js</a>, <a href="prism-core.js.html#line1205">line 1205</a>
     </li></ul></dd>
     
 
@@ -713,7 +713,7 @@ each another.</p></td>
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="prism-core.js.html">prism-core.js</a>, <a href="prism-core.js.html#line1213">line 1213</a>
+        <a href="prism-core.js.html">prism-core.js</a>, <a href="prism-core.js.html#line1215">line 1215</a>
     </li></ul></dd>
     
 

docs/prism-core.js.html

@@ -1100,6 +1100,7 @@ function LinkedList() {
 
 /**
  * Adds a new node with the given value to the list.
+ *
  * @param {LinkedList<T>} list
  * @param {LinkedListNode<T>} node
  * @param {T} value
@@ -1119,6 +1120,7 @@ function addAfter(list, node, value) {
 }
 /**
  * Removes `count` nodes after the given node. The given node will not be removed.
+ *
  * @param {LinkedList<T>} list
  * @param {LinkedListNode<T>} node
  * @param {number} count
@@ -1243,7 +1245,7 @@ if (typeof global !== 'undefined') {
  * each another.
  * @global
  * @public
-*/
+ */
 
 /**
  * @typedef Grammar
@@ -1261,7 +1263,7 @@ if (typeof global !== 'undefined') {
  * @returns {void}
  * @global
  * @public
-*/
+ */
 
 /**
  * @callback HookCallback

package-lock.json

@@ -1263,6 +1263,12 @@
       "integrity": "sha512-6tvAOO+D6OENvRAh524Dh9jcfKTYDQAqvqezbCW82xj5X0pSrcpxtvRKHLG0yBY6SD7PSDrJaj+0AiOcKVd1Xg==",
       "dev": true
     },
+    "comment-parser": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.1.2.tgz",
+      "integrity": "sha512-AOdq0i8ghZudnYv8RUnHrhTgafUGs61Rdz9jemU5x2lnZwAWyOq7vySo626K59e1fVKH1xSRorJwPVRLSWOoAQ==",
+      "dev": true
+    },
     "component-emitter": {
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/component-emitter/-/component-emitter-1.3.0.tgz",
@@ -2267,6 +2273,63 @@
         }
       }
     },
+    "eslint-plugin-jsdoc": {
+      "version": "32.3.0",
+      "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-32.3.0.tgz",
+      "integrity": "sha512-zyx7kajDK+tqS1bHuY5sapkad8P8KT0vdd/lE55j47VPG2MeenSYuIY/M/Pvmzq5g0+3JB+P3BJGUXmHxtuKPQ==",
+      "dev": true,
+      "requires": {
+        "comment-parser": "1.1.2",
+        "debug": "^4.3.1",
+        "jsdoctypeparser": "^9.0.0",
+        "lodash": "^4.17.20",
+        "regextras": "^0.7.1",
+        "semver": "^7.3.4",
+        "spdx-expression-parse": "^3.0.1"
+      },
+      "dependencies": {
+        "debug": {
+          "version": "4.3.1",
+          "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.1.tgz",
+          "integrity": "sha512-doEwdvm4PCeK4K3RQN2ZC2BYUBaxwLARCqZmMjtF8a51J2Rb0xpVloFRnCODwqjpwnAoao4pelN8l3RJdv3gRQ==",
+          "dev": true,
+          "requires": {
+            "ms": "2.1.2"
+          }
+        },
+        "lodash": {
+          "version": "4.17.21",
+          "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
+          "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==",
+          "dev": true
+        },
+        "ms": {
+          "version": "2.1.2",
+          "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz",
+          "integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==",
+          "dev": true
+        },
+        "semver": {
+          "version": "7.3.5",
+          "resolved": "https://registry.npmjs.org/semver/-/semver-7.3.5.tgz",
+          "integrity": "sha512-PoeGJYh8HK4BTO/a9Tf6ZG3veo/A7ZVsYrSA6J8ny9nb3B1VrpkuN+z9OE5wfE5p6H4LchYZsegiQgbJD94ZFQ==",
+          "dev": true,
+          "requires": {
+            "lru-cache": "^6.0.0"
+          }
+        },
+        "spdx-expression-parse": {
+          "version": "3.0.1",
+          "resolved": "https://registry.npmjs.org/spdx-expression-parse/-/spdx-expression-parse-3.0.1.tgz",
+          "integrity": "sha512-cbqHunsQWnJNE6KhVSMsMeH5H/L9EpymbzqTQ3uLwNCLZ1Q481oWaofqH7nO6V07xlXwY6PhQdQ2IedWx/ZK4Q==",
+          "dev": true,
+          "requires": {
+            "spdx-exceptions": "^2.1.0",
+            "spdx-license-ids": "^3.0.0"
+          }
+        }
+      }
+    },
     "eslint-scope": {
       "version": "5.1.1",
       "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-5.1.1.tgz",
@@ -3989,6 +4052,12 @@
         }
       }
     },
+    "jsdoctypeparser": {
+      "version": "9.0.0",
+      "resolved": "https://registry.npmjs.org/jsdoctypeparser/-/jsdoctypeparser-9.0.0.tgz",
+      "integrity": "sha512-jrTA2jJIL6/DAEILBEh2/w9QxCuwmvNXIry39Ay/HVfhE3o2yVV0U44blYkqdHA/OKloJEqvJy0xU+GSdE2SIw==",
+      "dev": true
+    },
     "jsdom": {
       "version": "13.2.0",
       "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-13.2.0.tgz",
@@ -5986,6 +6055,12 @@
       "integrity": "sha512-lv0M6+TkDVniA3aD1Eg0DVpfU/booSu7Eev3TDO/mZKHBfVjgCGTV4t4buppESEYDtkArYFOxTJWv6S5C+iaNw==",
       "dev": true
     },
+    "regextras": {
+      "version": "0.7.1",
+      "resolved": "https://registry.npmjs.org/regextras/-/regextras-0.7.1.tgz",
+      "integrity": "sha512-9YXf6xtW+qzQ+hcMQXx95MOvfqXFgsKDZodX3qZB0x2n5Z94ioetIITsBtvJbiOyxa/6s9AtyweBLCdPmPko/w==",
+      "dev": true
+    },
     "remove-bom-buffer": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/remove-bom-buffer/-/remove-bom-buffer-3.0.0.tgz",

package.json

@@ -38,6 +38,7 @@
     "del": "^4.1.1",
     "docdash": "^1.2.0",
     "eslint": "^7.22.0",
+    "eslint-plugin-jsdoc": "^32.3.0",
     "gulp": "^4.0.2",
     "gulp-concat": "^2.3.4",
     "gulp-header": "^2.0.7",

plugins/line-numbers/prism-line-numbers.js

@@ -6,12 +6,14 @@
 
 	/**
 	 * Plugin name which is used as a class name for <pre> which is activating the plugin
-	 * @type {String}
+	 *
+	 * @type {string}
 	 */
 	var PLUGIN_NAME = 'line-numbers';
 
 	/**
 	 * Regular expression used for determining line breaks
+	 *
 	 * @type {RegExp}
 	 */
 	var NEW_LINE_EXP = /\n(?!$)/g;
@@ -23,9 +25,10 @@
 	var config = Prism.plugins.lineNumbers = {
 		/**
 		 * Get node for provided line number
+		 *
 		 * @param {Element} element pre element
-		 * @param {Number} number line number
+		 * @param {number} number line number
-		 * @return {Element|undefined}
+		 * @returns {Element|undefined}
 		 */
 		getLine: function (element, number) {
 			if (element.tagName !== 'PRE' || !element.classList.contains(PLUGIN_NAME)) {
@@ -55,6 +58,7 @@
 		 * Resizes the line numbers of the given element.
 		 *
 		 * This function will not add line numbers. It will only resize existing ones.
+		 *
 		 * @param {HTMLElement} element A `<pre>` element with line numbers.
 		 * @returns {void}
 		 */
@@ -169,6 +173,7 @@
 
 	/**
 	 * Returns style declarations for the element
+	 *
 	 * @param {Element} element
 	 */
 	function getStyles(element) {

plugins/previewers/prism-previewers.js

@@ -15,6 +15,7 @@
 
 				/**
 				 * Returns a W3C-valid linear gradient
+				 *
 				 * @param {string} prefix Vendor prefix if any ("-moz-", "-webkit-", etc.)
 				 * @param {string} func Gradient function name ("linear-gradient")
 				 * @param {string[]} values Array of the gradient function parameters (["0deg", "red 0%", "blue 100%"])
@@ -64,6 +65,7 @@
 
 				/**
 				 * Returns a W3C-valid radial gradient
+				 *
 				 * @param {string} prefix Vendor prefix if any ("-moz-", "-webkit-", etc.)
 				 * @param {string} func Gradient function name ("linear-gradient")
 				 * @param {string[]} values Array of the gradient function parameters (["0deg", "red 0%", "blue 100%"])
@@ -108,6 +110,7 @@
 				/**
 				 * Converts a gradient to a W3C-valid one
 				 * Does not support old webkit syntax (-webkit-gradient(linear...) and -webkit-gradient(radial...))
+				 *
 				 * @param {string} gradient The CSS gradient
 				 */
 				var convertToW3CGradient = function(gradient) {
@@ -461,6 +464,7 @@
 
 	/**
 	 * Returns the absolute X, Y offsets for an element
+	 *
 	 * @param {HTMLElement} element
 	 * @returns {{top: number, right: number, bottom: number, left: number, width: number, height: number}}
 	 */
@@ -488,11 +492,12 @@
 
 	/**
 	 * Previewer constructor
+	 *
 	 * @param {string} type Unique previewer type
-	 * @param {function} updater Function that will be called on mouseover.
+	 * @param {Function} updater Function that will be called on mouseover.
-	 * @param {string[]|string=} supportedLanguages Aliases of the languages this previewer must be enabled for. Defaults to "*", all languages.
+	 * @param {string[]|string} [supportedLanguages] Aliases of the languages this previewer must be enabled for. Defaults to "*", all languages.
-	 * @param {function=} initializer Function that will be called on initialization.
+	 * @param {Function} [initializer] Function that will be called on initialization.
-	 * @constructor
+	 * @class
 	 */
 	var Previewer = function (type, updater, supportedLanguages, initializer) {
 		this._elt = null;
@@ -555,6 +560,7 @@
 
 	/**
 	 * Checks the class name of each hovered element
+	 *
 	 * @param {Element} token
 	 */
 	Previewer.prototype.check = function (token) {
@@ -624,18 +630,21 @@
 
 	/**
 	 * Map of all registered previewers by language
+	 *
 	 * @type {{}}
 	 */
 	Previewer.byLanguages = {};
 
 	/**
 	 * Map of all registered previewers by type
+	 *
 	 * @type {{}}
 	 */
 	Previewer.byType = {};
 
 	/**
 	 * Initializes the mouseover event on the code block.
+	 *
 	 * @param {HTMLElement} elt The code block (env.element)
 	 * @param {string} lang The language (env.language)
 	 */

prism.js

@@ -1052,6 +1052,7 @@ function LinkedList() {
 
 /**
  * Adds a new node with the given value to the list.
+ *
  * @param {LinkedList<T>} list
  * @param {LinkedListNode<T>} node
  * @param {T} value
@@ -1071,6 +1072,7 @@ function addAfter(list, node, value) {
 }
 /**
  * Removes `count` nodes after the given node. The given node will not be removed.
+ *
  * @param {LinkedList<T>} list
  * @param {LinkedListNode<T>} node
  * @param {number} count
@@ -1195,7 +1197,7 @@ if (typeof global !== 'undefined') {
  * each another.
  * @global
  * @public
-*/
+ */
 
 /**
  * @typedef Grammar
@@ -1213,7 +1215,7 @@ if (typeof global !== 'undefined') {
  * @returns {void}
  * @global
  * @public
-*/
+ */
 
 /**
  * @callback HookCallback

tests/helper/test-discovery.js

@@ -71,6 +71,7 @@ module.exports = {
 
 	/**
 	 * Returns whether a directory matches one of the given languages.
+	 *
 	 * @param {string} directory
 	 * @param {string|string[]} languages
 	 */

tests/identifier-test.js

@@ -170,7 +170,7 @@ function isNotBroken(token) {
  * Tests all patterns in the given Prism instance.
  *
  * @param {any} Prism
- * @param {lang} Prism
+ * @param {string} lang
  */
 function testLiterals(Prism, lang) {