Github
/
prism
mirror of
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

ESLint: Added JSDoc plugin (#2869)

This commit is contained in:
Michael Schmidt 2021-05-01 14:40:00 +02:00 committed by GitHub
parent b971ea2499
commit cf7b0fd503
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 138 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
.eslintrc.js
View File

@ -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/',

6
components/prism-core.js
View File

@ -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

8
components/prism-kumir.js
View File

@ -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) {

2
dependencies.js
View File

@ -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;

8
docs/global.html
View File

@ -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>

6
docs/prism-core.js.html
View File

@ -1100,6 +1100,7 @@ function LinkedList() {
/**
* Adds a new node with the given value to the list.
*
* @param {LinkedList&lt;T>} list
* @param {LinkedListNode&lt;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&lt;T>} list
* @param {LinkedListNode&lt;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

75
package-lock.json generated
View File

@ -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",

1
package.json
View File

@ -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",

11
plugins/line-numbers/prism-line-numbers.js
View File

@ -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
* @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 `<pre>` element with line numbers.
* @returns {void}
*/
@ -169,6 +173,7 @@
/**
* Returns style declarations for the element
*
* @param {Element} element
*/
function getStyles(element) {

17
plugins/previewers/prism-previewers.js
View File

@ -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)
*/

6
prism.js
View File

@ -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

1
tests/helper/test-discovery.js
View File

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

2
tests/identifier-test.js
View File

@ -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) {