356 lines
No EOL
10 KiB
JavaScript
356 lines
No EOL
10 KiB
JavaScript
"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 }; }
|
|
// If supporting Node >= 10, we could loosen the default to this for the
|
|
// initial letter: \\p{Upper}
|
|
const matchDescriptionDefault = '^\n?([A-Z`\\d_][\\s\\S]*[.?!`\\p{RGI_Emoji}]\\s*)?$';
|
|
|
|
/**
|
|
* @param {string} value
|
|
* @param {string} userDefault
|
|
* @returns {string}
|
|
*/
|
|
const stringOrDefault = (value, userDefault) => {
|
|
return typeof value === 'string' ? value : userDefault || matchDescriptionDefault;
|
|
};
|
|
var _default = exports.default = (0, _iterateJsdoc.default)(({
|
|
context,
|
|
jsdoc,
|
|
report,
|
|
utils
|
|
}) => {
|
|
const {
|
|
mainDescription,
|
|
matchDescription,
|
|
message,
|
|
nonemptyTags = true,
|
|
tags = {}
|
|
} = context.options[0] || {};
|
|
|
|
/**
|
|
* @param {string} desc
|
|
* @param {import('comment-parser').Spec} [tag]
|
|
* @returns {void}
|
|
*/
|
|
const validateDescription = (desc, tag) => {
|
|
let mainDescriptionMatch = mainDescription;
|
|
let errorMessage = message;
|
|
if (typeof mainDescription === 'object') {
|
|
mainDescriptionMatch = mainDescription.match;
|
|
errorMessage = mainDescription.message;
|
|
}
|
|
if (mainDescriptionMatch === false && (!tag || !Object.hasOwn(tags, tag.tag))) {
|
|
return;
|
|
}
|
|
let tagValue = mainDescriptionMatch;
|
|
if (tag) {
|
|
const tagName = tag.tag;
|
|
if (typeof tags[tagName] === 'object') {
|
|
tagValue = tags[tagName].match;
|
|
errorMessage = tags[tagName].message;
|
|
} else {
|
|
tagValue = tags[tagName];
|
|
}
|
|
}
|
|
const regex = utils.getRegexFromString(stringOrDefault(tagValue, matchDescription));
|
|
if (!regex.test(desc)) {
|
|
report(errorMessage || 'JSDoc description does not satisfy the regex pattern.', null, tag || {
|
|
// Add one as description would typically be into block
|
|
line: jsdoc.source[0].number + 1
|
|
});
|
|
}
|
|
};
|
|
const {
|
|
description
|
|
} = utils.getDescription();
|
|
if (description) {
|
|
validateDescription(description);
|
|
}
|
|
|
|
/**
|
|
* @param {string} tagName
|
|
* @returns {boolean}
|
|
*/
|
|
const hasNoTag = tagName => {
|
|
return !tags[tagName];
|
|
};
|
|
for (const tag of ['description', 'summary', 'file', 'classdesc']) {
|
|
utils.forEachPreferredTag(tag, (matchingJsdocTag, targetTagName) => {
|
|
const desc = (matchingJsdocTag.name + ' ' + utils.getTagDescription(matchingJsdocTag)).trim();
|
|
if (hasNoTag(targetTagName)) {
|
|
validateDescription(desc, matchingJsdocTag);
|
|
}
|
|
}, true);
|
|
}
|
|
if (nonemptyTags) {
|
|
for (const tag of ['copyright', 'example', 'see', 'todo']) {
|
|
utils.forEachPreferredTag(tag, (matchingJsdocTag, targetTagName) => {
|
|
const desc = (matchingJsdocTag.name + ' ' + utils.getTagDescription(matchingJsdocTag)).trim();
|
|
if (hasNoTag(targetTagName) && !/.+/v.test(desc)) {
|
|
report('JSDoc description must not be empty.', null, matchingJsdocTag);
|
|
}
|
|
});
|
|
}
|
|
}
|
|
if (!Object.keys(tags).length) {
|
|
return;
|
|
}
|
|
|
|
/**
|
|
* @param {string} tagName
|
|
* @returns {boolean}
|
|
*/
|
|
const hasOptionTag = tagName => {
|
|
return Boolean(tags[tagName]);
|
|
};
|
|
const whitelistedTags = utils.filterTags(({
|
|
tag: tagName
|
|
}) => {
|
|
return hasOptionTag(tagName);
|
|
});
|
|
const {
|
|
tagsWithNames,
|
|
tagsWithoutNames
|
|
} = utils.getTagsByType(whitelistedTags);
|
|
tagsWithNames.some(tag => {
|
|
const desc = /** @type {string} */utils.getTagDescription(tag).replace(/^[\- ]*/v, '').trim();
|
|
return validateDescription(desc, tag);
|
|
});
|
|
tagsWithoutNames.some(tag => {
|
|
const desc = (tag.name + ' ' + utils.getTagDescription(tag)).trim();
|
|
return validateDescription(desc, tag);
|
|
});
|
|
}, {
|
|
contextDefaults: true,
|
|
meta: {
|
|
docs: {
|
|
description: 'Enforces a regular expression pattern on descriptions.',
|
|
url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/match-description.md#repos-sticky-header'
|
|
},
|
|
schema: [{
|
|
additionalProperties: false,
|
|
properties: {
|
|
contexts: {
|
|
description: `Set this to an array of strings representing the AST context (or an object with
|
|
optional \`context\` and \`comment\` properties) where you wish the rule to be applied (e.g.,
|
|
\`ClassDeclaration\` for ES6 classes).
|
|
|
|
\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
|
|
|
|
Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
|
|
\`FunctionExpression\`). Set to \`"any"\` if you want the rule to apply to any
|
|
JSDoc block throughout your files.
|
|
|
|
See the ["AST and Selectors"](../#advanced-ast-and-selectors)
|
|
section of our Advanced docs for more on the expected format.`,
|
|
items: {
|
|
anyOf: [{
|
|
type: 'string'
|
|
}, {
|
|
additionalProperties: false,
|
|
properties: {
|
|
comment: {
|
|
type: 'string'
|
|
},
|
|
context: {
|
|
type: 'string'
|
|
}
|
|
},
|
|
type: 'object'
|
|
}]
|
|
},
|
|
type: 'array'
|
|
},
|
|
mainDescription: {
|
|
description: `If you wish to override the main block description without changing the
|
|
default \`match-description\` (which can cascade to the \`tags\` with \`true\`),
|
|
you may use \`mainDescription\`:
|
|
|
|
\`\`\`js
|
|
{
|
|
'jsdoc/match-description': ['error', {
|
|
mainDescription: '[A-Z].*\\\\.',
|
|
tags: {
|
|
param: true,
|
|
returns: true
|
|
}
|
|
}]
|
|
}
|
|
\`\`\`
|
|
|
|
There is no need to add \`mainDescription: true\`, as by default, the main
|
|
block description (and only the main block description) is linted, though you
|
|
may disable checking it by setting it to \`false\`.
|
|
|
|
You may also provide an object with \`message\`:
|
|
|
|
\`\`\`js
|
|
{
|
|
'jsdoc/match-description': ['error', {
|
|
mainDescription: {
|
|
message: 'Capitalize first word of JSDoc block descriptions',
|
|
match: '[A-Z].*\\\\.'
|
|
},
|
|
tags: {
|
|
param: true,
|
|
returns: true
|
|
}
|
|
}]
|
|
}
|
|
\`\`\``,
|
|
oneOf: [{
|
|
format: 'regex',
|
|
type: 'string'
|
|
}, {
|
|
type: 'boolean'
|
|
}, {
|
|
additionalProperties: false,
|
|
properties: {
|
|
match: {
|
|
oneOf: [{
|
|
format: 'regex',
|
|
type: 'string'
|
|
}, {
|
|
type: 'boolean'
|
|
}]
|
|
},
|
|
message: {
|
|
type: 'string'
|
|
}
|
|
},
|
|
type: 'object'
|
|
}]
|
|
},
|
|
matchDescription: {
|
|
description: `You can supply your own expression to override the default, passing a
|
|
\`matchDescription\` string on the options object.
|
|
|
|
Defaults to using (only) the \`v\` flag, so
|
|
to add your own flags, encapsulate your expression as a string, but like a
|
|
literal, e.g., \`/[A-Z].*\\./vi\`.
|
|
|
|
\`\`\`js
|
|
{
|
|
'jsdoc/match-description': ['error', {matchDescription: '[A-Z].*\\\\.'}]
|
|
}
|
|
\`\`\``,
|
|
format: 'regex',
|
|
type: 'string'
|
|
},
|
|
message: {
|
|
description: `You may provide a custom default message by using the following format:
|
|
|
|
\`\`\`js
|
|
{
|
|
'jsdoc/match-description': ['error', {
|
|
message: 'The default description should begin with a capital letter.'
|
|
}]
|
|
}
|
|
\`\`\`
|
|
|
|
This can be overridden per tag or for the main block description by setting
|
|
\`message\` within \`tags\` or \`mainDescription\`, respectively.`,
|
|
type: 'string'
|
|
},
|
|
nonemptyTags: {
|
|
description: `If not set to \`false\`, will enforce that the following tags have at least
|
|
some content:
|
|
|
|
- \`@copyright\`
|
|
- \`@example\`
|
|
- \`@see\`
|
|
- \`@todo\`
|
|
|
|
If you supply your own tag description for any of the above tags in \`tags\`,
|
|
your description will take precedence.`,
|
|
type: 'boolean'
|
|
},
|
|
tags: {
|
|
description: `If you want different regular expressions to apply to tags, you may use
|
|
the \`tags\` option object:
|
|
|
|
\`\`\`js
|
|
{
|
|
'jsdoc/match-description': ['error', {tags: {
|
|
param: '\\\\- [A-Z].*\\\\.',
|
|
returns: '[A-Z].*\\\\.'
|
|
}}]
|
|
}
|
|
\`\`\`
|
|
|
|
In place of a string, you can also add \`true\` to indicate that a particular
|
|
tag should be linted with the \`matchDescription\` value (or the default).
|
|
|
|
\`\`\`js
|
|
{
|
|
'jsdoc/match-description': ['error', {tags: {
|
|
param: true,
|
|
returns: true
|
|
}}]
|
|
}
|
|
\`\`\`
|
|
|
|
Alternatively, you may supply an object with a \`message\` property to indicate
|
|
the error message for that tag.
|
|
|
|
\`\`\`js
|
|
{
|
|
'jsdoc/match-description': ['error', {tags: {
|
|
param: {message: 'Begin with a hyphen', match: '\\\\- [A-Z].*\\\\.'},
|
|
returns: {message: 'Capitalize for returns (the default)', match: true}
|
|
}}]
|
|
}
|
|
\`\`\`
|
|
|
|
The tags \`@param\`/\`@arg\`/\`@argument\` and \`@property\`/\`@prop\` will be properly
|
|
parsed to ensure that the matched "description" text includes only the text
|
|
after the name.
|
|
|
|
All other tags will treat the text following the tag name, a space, and
|
|
an optional curly-bracketed type expression (and another space) as part of
|
|
its "description" (e.g., for \`@returns {someType} some description\`, the
|
|
description is \`some description\` while for \`@some-tag xyz\`, the description
|
|
is \`xyz\`).`,
|
|
patternProperties: {
|
|
'.*': {
|
|
oneOf: [{
|
|
format: 'regex',
|
|
type: 'string'
|
|
}, {
|
|
enum: [true],
|
|
type: 'boolean'
|
|
}, {
|
|
additionalProperties: false,
|
|
properties: {
|
|
match: {
|
|
oneOf: [{
|
|
format: 'regex',
|
|
type: 'string'
|
|
}, {
|
|
enum: [true],
|
|
type: 'boolean'
|
|
}]
|
|
},
|
|
message: {
|
|
type: 'string'
|
|
}
|
|
},
|
|
type: 'object'
|
|
}]
|
|
}
|
|
},
|
|
type: 'object'
|
|
}
|
|
},
|
|
type: 'object'
|
|
}],
|
|
type: 'suggestion'
|
|
}
|
|
});
|
|
module.exports = exports.default;
|
|
//# sourceMappingURL=matchDescription.cjs.map
|