diff --git a/.eslintrc.js b/.eslintrc.js index a9b1b0b6..ae60a759 100644 --- a/.eslintrc.js +++ b/.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/', diff --git a/components/prism-core.js b/components/prism-core.js index f68943d4..d19999d3 100644 --- a/components/prism-core.js +++ b/components/prism-core.js @@ -1047,6 +1047,7 @@ function LinkedList() { /** * Adds a new node with the given value to the list. + * * @param {LinkedList} list * @param {LinkedListNode} 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} list * @param {LinkedListNode} 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 diff --git a/components/prism-kumir.js b/components/prism-kumir.js index 76fa06c1..7d704e52 100644 --- a/components/prism-kumir.js +++ b/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) { diff --git a/dependencies.js b/dependencies.js index a9e25c3d..ab35ae95 100644 --- a/dependencies.js +++ b/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; diff --git a/docs/global.html b/docs/global.html index 0a4ffd8f..550ab58a 100644 --- a/docs/global.html +++ b/docs/global.html @@ -143,7 +143,7 @@
Source:
@@ -274,7 +274,7 @@
Source:
@@ -559,7 +559,7 @@ each another.

Source:
@@ -713,7 +713,7 @@ each another.

Source:
diff --git a/docs/prism-core.js.html b/docs/prism-core.js.html index 4fe0ce33..229462b3 100644 --- a/docs/prism-core.js.html +++ b/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 diff --git a/package-lock.json b/package-lock.json index 06946179..f13f0641 100644 --- a/package-lock.json +++ b/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", diff --git a/package.json b/package.json index a6b14e01..a86c5490 100755 --- a/package.json +++ b/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", diff --git a/plugins/line-numbers/prism-line-numbers.js b/plugins/line-numbers/prism-line-numbers.js index dd5cdc5d..71e8b696 100644 --- a/plugins/line-numbers/prism-line-numbers.js +++ b/plugins/line-numbers/prism-line-numbers.js @@ -6,12 +6,14 @@ /** * Plugin name which is used as a class name for 
 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
-		 * @return {Element|undefined}
+		 * @param {number} number line number
+		 * @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 `
` element with line numbers.
 		 * @returns {void}
 		 */
@@ -169,6 +173,7 @@
 
 	/**
 	 * Returns style declarations for the element
+	 *
 	 * @param {Element} element
 	 */
 	function getStyles(element) {
diff --git a/plugins/previewers/prism-previewers.js b/plugins/previewers/prism-previewers.js
index 17e33892..a385af14 100644
--- a/plugins/previewers/prism-previewers.js
+++ b/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 {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.
-	 * @constructor
+	 * @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 {Function} [initializer] Function that will be called on initialization.
+	 * @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)
 	 */
diff --git a/prism.js b/prism.js
index 25748745..95fb799f 100644
--- a/prism.js
+++ b/prism.js
@@ -1052,6 +1052,7 @@ function LinkedList() {
 
 /**
  * Adds a new node with the given value to the list.
+ *
  * @param {LinkedList} list
  * @param {LinkedListNode} 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} list
  * @param {LinkedListNode} 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
diff --git a/tests/helper/test-discovery.js b/tests/helper/test-discovery.js
index 053039ac..9380e342 100644
--- a/tests/helper/test-discovery.js
+++ b/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
 	 */
diff --git a/tests/identifier-test.js b/tests/identifier-test.js
index e69c0273..bc8ef401 100644
--- a/tests/identifier-test.js
+++ b/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) {