Website Structure
This commit is contained in:
supalerk-ar66
parent
62812f2090
commit
71f0676a62
22365 changed files with 4265753 additions and 791 deletions
431
Frontend-Learner/node_modules/eslint-plugin-jsdoc/dist/rules/multilineBlocks.cjs
generated
vendored
Normal file
431
Frontend-Learner/node_modules/eslint-plugin-jsdoc/dist/rules/multilineBlocks.cjs
generated
vendored
Normal file
|
|
@ -0,0 +1,431 @@
|
|||
"use strict";
|
||||
|
||||
Object.defineProperty(exports, "__esModule", {
|
||||
value: true
|
||||
});
|
||||
exports.default = void 0;
|
||||
var _iterateJsdoc = _interopRequireDefault(require("../iterateJsdoc.cjs"));
|
||||
function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
|
||||
/**
|
||||
* @param {import('@es-joy/jsdoccomment').JsdocBlockWithInline} jsdoc
|
||||
* @param {import('../iterateJsdoc.js').Utils} utils
|
||||
* @param {number} requireSingleLineUnderCount
|
||||
*/
|
||||
const checkForShortTags = (jsdoc, utils, requireSingleLineUnderCount) => {
|
||||
if (!requireSingleLineUnderCount || !jsdoc.tags.length) {
|
||||
return false;
|
||||
}
|
||||
let lastLineWithTag = 0;
|
||||
let isUnderCountLimit = false;
|
||||
let hasMultiDescOrType = false;
|
||||
const tagLines = jsdoc.source.reduce((acc, {
|
||||
tokens: {
|
||||
delimiter,
|
||||
description: desc,
|
||||
name,
|
||||
postDelimiter,
|
||||
postName,
|
||||
postTag,
|
||||
postType,
|
||||
start,
|
||||
tag,
|
||||
type
|
||||
}
|
||||
}, idx) => {
|
||||
if (tag.length) {
|
||||
lastLineWithTag = idx;
|
||||
if (start.length + delimiter.length + postDelimiter.length + type.length + postType.length + name.length + postName.length + tag.length + postTag.length + desc.length < requireSingleLineUnderCount) {
|
||||
isUnderCountLimit = true;
|
||||
}
|
||||
return acc + 1;
|
||||
} else if (desc.length || type.length) {
|
||||
hasMultiDescOrType = true;
|
||||
return acc;
|
||||
}
|
||||
return acc;
|
||||
}, 0);
|
||||
// Could be tagLines > 1
|
||||
if (!hasMultiDescOrType && isUnderCountLimit && tagLines === 1) {
|
||||
const fixer = () => {
|
||||
const tokens = jsdoc.source[lastLineWithTag].tokens;
|
||||
jsdoc.source = [{
|
||||
number: 0,
|
||||
source: '',
|
||||
tokens: utils.seedTokens({
|
||||
delimiter: '/**',
|
||||
description: tokens.description.trimEnd() + ' ',
|
||||
end: '*/',
|
||||
name: tokens.name,
|
||||
postDelimiter: ' ',
|
||||
postName: tokens.postName,
|
||||
postTag: tokens.postTag,
|
||||
postType: tokens.postType,
|
||||
start: jsdoc.source[0].tokens.start,
|
||||
tag: tokens.tag,
|
||||
type: tokens.type
|
||||
})
|
||||
}];
|
||||
};
|
||||
utils.reportJSDoc('Description is too short to be multi-line.', null, fixer);
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
};
|
||||
|
||||
/**
|
||||
* @param {import('@es-joy/jsdoccomment').JsdocBlockWithInline} jsdoc
|
||||
* @param {import('../iterateJsdoc.js').Utils} utils
|
||||
* @param {number} requireSingleLineUnderCount
|
||||
*/
|
||||
const checkForShortDescriptions = (jsdoc, utils, requireSingleLineUnderCount) => {
|
||||
if (!requireSingleLineUnderCount || jsdoc.tags.length) {
|
||||
return false;
|
||||
}
|
||||
let lastLineWithDesc = 0;
|
||||
let isUnderCountLimit = false;
|
||||
const descLines = jsdoc.source.reduce((acc, {
|
||||
tokens: {
|
||||
delimiter,
|
||||
description: desc,
|
||||
postDelimiter,
|
||||
start
|
||||
}
|
||||
}, idx) => {
|
||||
if (desc.length) {
|
||||
lastLineWithDesc = idx;
|
||||
if (start.length + delimiter.length + postDelimiter.length + desc.length < requireSingleLineUnderCount) {
|
||||
isUnderCountLimit = true;
|
||||
}
|
||||
return acc + 1;
|
||||
}
|
||||
return acc;
|
||||
}, 0);
|
||||
// Could be descLines > 1
|
||||
if (isUnderCountLimit && descLines === 1) {
|
||||
const fixer = () => {
|
||||
const desc = jsdoc.source[lastLineWithDesc].tokens.description;
|
||||
jsdoc.source = [{
|
||||
number: 0,
|
||||
source: '',
|
||||
tokens: utils.seedTokens({
|
||||
delimiter: '/**',
|
||||
description: desc.trimEnd() + ' ',
|
||||
end: '*/',
|
||||
postDelimiter: ' ',
|
||||
start: jsdoc.source[0].tokens.start
|
||||
})
|
||||
}];
|
||||
};
|
||||
utils.reportJSDoc('Description is too short to be multi-line.', null, fixer);
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
};
|
||||
var _default = exports.default = (0, _iterateJsdoc.default)(({
|
||||
context,
|
||||
jsdoc,
|
||||
utils
|
||||
}) => {
|
||||
const {
|
||||
allowMultipleTags = true,
|
||||
minimumLengthForMultiline = Number.POSITIVE_INFINITY,
|
||||
multilineTags = ['*'],
|
||||
noFinalLineText = true,
|
||||
noMultilineBlocks = false,
|
||||
noSingleLineBlocks = false,
|
||||
noZeroLineText = true,
|
||||
requireSingleLineUnderCount = null,
|
||||
singleLineTags = ['lends', 'type']
|
||||
} = context.options[0] || {};
|
||||
const {
|
||||
source: [{
|
||||
tokens
|
||||
}]
|
||||
} = jsdoc;
|
||||
const {
|
||||
description,
|
||||
tag
|
||||
} = tokens;
|
||||
const sourceLength = jsdoc.source.length;
|
||||
|
||||
/**
|
||||
* @param {string} tagName
|
||||
* @returns {boolean}
|
||||
*/
|
||||
const isInvalidSingleLine = tagName => {
|
||||
return noSingleLineBlocks && (!tagName || !singleLineTags.includes(tagName) && !singleLineTags.includes('*'));
|
||||
};
|
||||
if (sourceLength === 1) {
|
||||
if (!isInvalidSingleLine(tag.slice(1))) {
|
||||
return;
|
||||
}
|
||||
const fixer = () => {
|
||||
utils.makeMultiline();
|
||||
};
|
||||
utils.reportJSDoc('Single line blocks are not permitted by your configuration.', null, fixer, true);
|
||||
return;
|
||||
}
|
||||
if (checkForShortDescriptions(jsdoc, utils, requireSingleLineUnderCount)) {
|
||||
return;
|
||||
}
|
||||
if (checkForShortTags(jsdoc, utils, requireSingleLineUnderCount)) {
|
||||
return;
|
||||
}
|
||||
const lineChecks = () => {
|
||||
if (noZeroLineText && (tag || description)) {
|
||||
const fixer = () => {
|
||||
const line = {
|
||||
...tokens
|
||||
};
|
||||
utils.emptyTokens(tokens);
|
||||
const {
|
||||
tokens: {
|
||||
delimiter,
|
||||
start
|
||||
}
|
||||
} = jsdoc.source[1];
|
||||
utils.addLine(1, {
|
||||
...line,
|
||||
delimiter,
|
||||
start
|
||||
});
|
||||
};
|
||||
utils.reportJSDoc('Should have no text on the "0th" line (after the `/**`).', null, fixer);
|
||||
return;
|
||||
}
|
||||
const finalLine = jsdoc.source[jsdoc.source.length - 1];
|
||||
const finalLineTokens = finalLine.tokens;
|
||||
if (noFinalLineText && finalLineTokens.description.trim()) {
|
||||
const fixer = () => {
|
||||
const line = {
|
||||
...finalLineTokens
|
||||
};
|
||||
line.description = line.description.trimEnd();
|
||||
const {
|
||||
delimiter
|
||||
} = line;
|
||||
for (const prop of ['delimiter', 'postDelimiter', 'tag', 'type', 'lineEnd', 'postType', 'postTag', 'name', 'postName', 'description']) {
|
||||
finalLineTokens[(
|
||||
/**
|
||||
* @type {"delimiter"|"postDelimiter"|"tag"|"type"|
|
||||
* "lineEnd"|"postType"|"postTag"|"name"|
|
||||
* "postName"|"description"}
|
||||
*/
|
||||
prop)] = '';
|
||||
}
|
||||
utils.addLine(jsdoc.source.length - 1, {
|
||||
...line,
|
||||
delimiter,
|
||||
end: ''
|
||||
});
|
||||
};
|
||||
utils.reportJSDoc('Should have no text on the final line (before the `*/`).', null, fixer);
|
||||
}
|
||||
};
|
||||
if (noMultilineBlocks) {
|
||||
if (jsdoc.tags.length && (multilineTags.includes('*') || utils.hasATag(multilineTags))) {
|
||||
lineChecks();
|
||||
return;
|
||||
}
|
||||
if (jsdoc.description.length >= minimumLengthForMultiline) {
|
||||
lineChecks();
|
||||
return;
|
||||
}
|
||||
if (noSingleLineBlocks && (!jsdoc.tags.length || !utils.filterTags(({
|
||||
tag: tg
|
||||
}) => {
|
||||
return !isInvalidSingleLine(tg);
|
||||
}).length)) {
|
||||
utils.reportJSDoc('Multiline JSDoc blocks are prohibited by ' + 'your configuration but fixing would result in a single ' + 'line block which you have prohibited with `noSingleLineBlocks`.');
|
||||
return;
|
||||
}
|
||||
if (jsdoc.tags.length > 1) {
|
||||
if (!allowMultipleTags) {
|
||||
utils.reportJSDoc('Multiline JSDoc blocks are prohibited by ' + 'your configuration but the block has multiple tags.');
|
||||
return;
|
||||
}
|
||||
} else if (jsdoc.tags.length === 1 && jsdoc.description.trim()) {
|
||||
if (!allowMultipleTags) {
|
||||
utils.reportJSDoc('Multiline JSDoc blocks are prohibited by ' + 'your configuration but the block has a description with a tag.');
|
||||
return;
|
||||
}
|
||||
} else {
|
||||
const fixer = () => {
|
||||
jsdoc.source = [{
|
||||
number: 1,
|
||||
source: '',
|
||||
tokens: jsdoc.source.reduce((obj, {
|
||||
tokens: {
|
||||
description: desc,
|
||||
lineEnd,
|
||||
name: nme,
|
||||
postName,
|
||||
postTag,
|
||||
postType,
|
||||
tag: tg,
|
||||
type: typ
|
||||
}
|
||||
}) => {
|
||||
if (typ) {
|
||||
obj.type = typ;
|
||||
}
|
||||
if (tg && typ && nme) {
|
||||
obj.postType = postType;
|
||||
}
|
||||
if (nme) {
|
||||
obj.name += nme;
|
||||
}
|
||||
if (nme && desc) {
|
||||
obj.postName = postName;
|
||||
}
|
||||
obj.description += desc;
|
||||
const nameOrDescription = obj.description || obj.name;
|
||||
if (nameOrDescription && nameOrDescription.slice(-1) !== ' ') {
|
||||
obj.description += ' ';
|
||||
}
|
||||
obj.lineEnd = lineEnd;
|
||||
|
||||
// Already filtered for multiple tags
|
||||
obj.tag += tg;
|
||||
if (tg) {
|
||||
obj.postTag = postTag || ' ';
|
||||
}
|
||||
return obj;
|
||||
}, utils.seedTokens({
|
||||
delimiter: '/**',
|
||||
end: '*/',
|
||||
postDelimiter: ' '
|
||||
}))
|
||||
}];
|
||||
};
|
||||
utils.reportJSDoc('Multiline JSDoc blocks are prohibited by ' + 'your configuration.', null, fixer);
|
||||
return;
|
||||
}
|
||||
}
|
||||
lineChecks();
|
||||
}, {
|
||||
iterateAllJsdocs: true,
|
||||
meta: {
|
||||
docs: {
|
||||
description: 'Controls how and whether JSDoc blocks can be expressed as single or multiple line blocks.',
|
||||
url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/multiline-blocks.md#repos-sticky-header'
|
||||
},
|
||||
fixable: 'code',
|
||||
schema: [{
|
||||
additionalProperties: false,
|
||||
properties: {
|
||||
allowMultipleTags: {
|
||||
description: `If \`noMultilineBlocks\` is set to \`true\` with this option and multiple tags are
|
||||
found in a block, an error will not be reported.
|
||||
|
||||
Since multiple-tagged lines cannot be collapsed into a single line, this option
|
||||
prevents them from being reported. Set to \`false\` if you really want to report
|
||||
any blocks.
|
||||
|
||||
This option will also be applied when there is a block description and a single
|
||||
tag (since a description cannot precede a tag on a single line, and also
|
||||
cannot be reliably added after the tag either).
|
||||
|
||||
Defaults to \`true\`.`,
|
||||
type: 'boolean'
|
||||
},
|
||||
minimumLengthForMultiline: {
|
||||
description: `If \`noMultilineBlocks\` is set with this numeric option, multiline blocks will
|
||||
be permitted if containing at least the given amount of text.
|
||||
|
||||
If not set, multiline blocks will not be permitted regardless of length unless
|
||||
a relevant tag is present and \`multilineTags\` is set.
|
||||
|
||||
Defaults to not being in effect.`,
|
||||
type: 'integer'
|
||||
},
|
||||
multilineTags: {
|
||||
anyOf: [{
|
||||
enum: ['*'],
|
||||
type: 'string'
|
||||
}, {
|
||||
items: {
|
||||
type: 'string'
|
||||
},
|
||||
type: 'array'
|
||||
}],
|
||||
description: `If \`noMultilineBlocks\` is set with this option, multiline blocks may be allowed
|
||||
regardless of length as long as a tag or a tag of a certain type is present.
|
||||
|
||||
If \`*\` is included in the array, the presence of a tags will allow for
|
||||
multiline blocks (but not when without any tags unless the amount of text is
|
||||
over an amount specified by \`minimumLengthForMultiline\`).
|
||||
|
||||
If the array does not include \`*\` but lists certain tags, the presence of
|
||||
such a tag will cause multiline blocks to be allowed.
|
||||
|
||||
You may set this to an empty array to prevent any tag from permitting multiple
|
||||
lines.
|
||||
|
||||
Defaults to \`['*']\`.`
|
||||
},
|
||||
noFinalLineText: {
|
||||
description: `For multiline blocks, any non-whitespace text preceding the \`*/\` on the final
|
||||
line will be reported. (Text preceding a newline is not reported.)
|
||||
|
||||
\`noMultilineBlocks\` will have priority over this rule if it applies.
|
||||
|
||||
Defaults to \`true\`.`,
|
||||
type: 'boolean'
|
||||
},
|
||||
noMultilineBlocks: {
|
||||
description: `Requires that JSDoc blocks are restricted to single lines only unless impacted
|
||||
by the options \`minimumLengthForMultiline\`, \`multilineTags\`, or
|
||||
\`allowMultipleTags\`.
|
||||
|
||||
Defaults to \`false\`.`,
|
||||
type: 'boolean'
|
||||
},
|
||||
noSingleLineBlocks: {
|
||||
description: `If this is \`true\`, any single line blocks will be reported, except those which
|
||||
are whitelisted in \`singleLineTags\`.
|
||||
|
||||
Defaults to \`false\`.`,
|
||||
type: 'boolean'
|
||||
},
|
||||
noZeroLineText: {
|
||||
description: `For multiline blocks, any non-whitespace text immediately after the \`/**\` and
|
||||
space will be reported. (Text after a newline is not reported.)
|
||||
|
||||
\`noMultilineBlocks\` will have priority over this rule if it applies.
|
||||
|
||||
Defaults to \`true\`.`,
|
||||
type: 'boolean'
|
||||
},
|
||||
requireSingleLineUnderCount: {
|
||||
description: `If this number is set, it indicates a minimum line width for a single line of
|
||||
JSDoc content spread over a multi-line comment block. If a single line is under
|
||||
the minimum length, it will be reported so as to enforce single line JSDoc blocks
|
||||
for such cases. Blocks are not reported which have multi-line descriptions,
|
||||
multiple tags, a block description and tag, or tags with multi-line types or
|
||||
descriptions.
|
||||
|
||||
Defaults to \`null\`.`,
|
||||
type: 'number'
|
||||
},
|
||||
singleLineTags: {
|
||||
description: `An array of tags which can nevertheless be allowed as single line blocks when
|
||||
\`noSingleLineBlocks\` is set. You may set this to a empty array to
|
||||
cause all single line blocks to be reported. If \`'*'\` is present, then
|
||||
the presence of a tag will allow single line blocks (but not if a tag is
|
||||
missing).
|
||||
|
||||
Defaults to \`['lends', 'type']\`.`,
|
||||
items: {
|
||||
type: 'string'
|
||||
},
|
||||
type: 'array'
|
||||
}
|
||||
},
|
||||
type: 'object'
|
||||
}],
|
||||
type: 'suggestion'
|
||||
}
|
||||
});
|
||||
module.exports = exports.default;
|
||||
//# sourceMappingURL=multilineBlocks.cjs.map
|
||||
Loading…
Add table
Add a link
Reference in a new issue