diff --git a/.README/rules/match-description.md b/.README/rules/match-description.md
index c8ec95a11..c2667b20f 100644
--- a/.README/rules/match-description.md
+++ b/.README/rules/match-description.md
@@ -50,14 +50,39 @@ tag should be linted with the `matchDescription` value (or the default).
}
```
+If you wish to override the main function description without changing the
+default `mainDescription`, you may use `tags` with `main description`:
-By default, only the main function description is linted.
+```js
+{
+ 'jsdoc/match-description': ['error', {tags: {
+ 'main description': '[A-Z].*\\.',
+ param: true,
+ returns: true
+ }}]
+}
+```
+
+There is no need to add `"main description": true`, as by default, the main
+function (and only the main function) is linted, though you may disable checking
+it by setting it to `false`.
+
+##### `contexts`
+
+Set this to a string or array of strings representing the AST context
+where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
+
+##### `noDefaults`
+
+By default, `contexts` will permit `ArrowFunctionExpression`,
+`FunctionDeclaration`, and `FunctionExpression`. Set this instead to `true` to
+have `contexts` override these.
|||
|---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
|Tags|N/A by default but see `tags` options|
|Settings||
-|Options|`tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
+|Options|`contexts`, `noDefaults`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
diff --git a/README.md b/README.md
index 503533807..bf6bf975d 100644
--- a/README.md
+++ b/README.md
@@ -2299,15 +2299,42 @@ tag should be linted with the `matchDescription` value (or the default).
}
```
+If you wish to override the main function description without changing the
+default `mainDescription`, you may use `tags` with `main description`:
-By default, only the main function description is linted.
+```js
+{
+ 'jsdoc/match-description': ['error', {tags: {
+ 'main description': '[A-Z].*\\.',
+ param: true,
+ returns: true
+ }}]
+}
+```
+
+There is no need to add `"main description": true`, as by default, the main
+function (and only the main function) is linted, though you may disable checking
+it by setting it to `false`.
+
+
+##### contexts
+
+Set this to a string or array of strings representing the AST context
+where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
+
+
+##### noDefaults
+
+By default, `contexts` will permit `ArrowFunctionExpression`,
+`FunctionDeclaration`, and `FunctionExpression`. Set this instead to `true` to
+have `contexts` override these.
|||
|---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
|Tags|N/A by default but see `tags` options|
|Settings||
-|Options|`tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
+|Options|`contexts`, `noDefaults`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
The following patterns are considered problems:
@@ -2335,6 +2362,18 @@ function quux () {
}
// Options: [{"matchDescription":"[А-Я][А-я]+\\."}]
+<<<<<<< HEAD
+=======
+// Message: JSDoc description does not satisfy the regex pattern.
+
+/**
+ * тест.
+ */
+function quux () {
+
+}
+// Options: [{"tags":{"main description":"[А-Я][А-я]+\\.","param":true}}]
+>>>>>>> feat(match-description): allow `main description: string|boolean` to override or disable main description separate from default
// Message: JSDoc description does not satisfy the regex pattern.
/**
@@ -2356,6 +2395,28 @@ function quux (foo) {
// Options: [{"tags":{"param":true}}]
// Message: JSDoc description does not satisfy the regex pattern.
+/**
+ * Foo
+ *
+ * @param foo foo.
+ */
+function quux (foo) {
+
+}
+// Options: [{"tags":{"main description":"^[a-zA-Z]*$","param":true}}]
+// Message: JSDoc description does not satisfy the regex pattern.
+
+/**
+ * Foo
+ *
+ * @param foo foo.
+ */
+function quux (foo) {
+
+}
+// Options: [{"tags":{"main description":false,"param":true}}]
+// Message: JSDoc description does not satisfy the regex pattern.
+
/**
* Foo.
*
@@ -2456,6 +2517,18 @@ function quux () {
}
// Options: [{"tags":{"param":"[А-Я][А-я]+\\."}}]
+<<<<<<< HEAD
+=======
+// Message: JSDoc description does not satisfy the regex pattern.
+
+/**
+ * foo.
+ */
+class quux {
+
+}
+// Options: [{"contexts":["ClassDeclaration"],"noDefaults":true}]
+>>>>>>> feat(match-description): allow `main description: string|boolean` to override or disable main description separate from default
// Message: JSDoc description does not satisfy the regex pattern.
````
@@ -2585,6 +2658,30 @@ function quux () {
function quux () {
}
+
+/**
+ * foo.
+ */
+function quux () {
+
+}
+// Options: [{"tags":{"main description":false}}]
+
+/**
+ * foo.
+ */
+class quux {
+
+}
+// Message: JSDoc description does not satisfy the regex pattern.
+
+/**
+ * foo.
+ */
+class quux {
+
+}
+// Options: [{"tags":{"main description":true}}]
````
diff --git a/src/rules/matchDescription.js b/src/rules/matchDescription.js
index 3f9c21e84..340519435 100644
--- a/src/rules/matchDescription.js
+++ b/src/rules/matchDescription.js
@@ -12,8 +12,13 @@ export default iterateJsdoc(({
const options = context.options[0] || {};
const validateDescription = (description, tag) => {
+ const tagName = tag.tag;
+ const tagOptions = options.tags || {};
+ if (tagOptions[tagName] === false) {
+ return;
+ }
const regex = new RegExp(
- (tag && typeof options.tags[tag] === 'string' ? options.tags[tag] :
+ (typeof tagOptions[tagName] === 'string' ? tagOptions[tagName] :
options.matchDescription
// If supporting Node >= 10, we could loosen to this for the
@@ -23,16 +28,16 @@ export default iterateJsdoc(({
);
if (!regex.test(description)) {
- report('JSDoc description does not satisfy the regex pattern.');
-
- return true;
+ report('JSDoc description does not satisfy the regex pattern.', null, tag);
}
-
- return false;
};
- if (jsdoc.description && validateDescription(jsdoc.description)) {
- return;
+ if (jsdoc.description) {
+ validateDescription(jsdoc.description, {
+ // Add one as description would typically be into block
+ line: jsdoc.line + 1,
+ tag: 'main description'
+ });
}
if (!options.tags || !Object.keys(options.tags).length) {
@@ -47,18 +52,36 @@ export default iterateJsdoc(({
tags.some((tag) => {
const description = _.trimStart(tag.description, '- ');
- return validateDescription(description, tag.tag);
+ return validateDescription(description, tag);
});
}, {
+ contextDefaults: true,
meta: {
schema: [
{
additionalProperties: false,
properties: {
+ contexts: {
+ oneOf: [
+ {
+ items: {
+ type: 'string'
+ },
+ type: 'array'
+ },
+ {
+ type: 'string'
+ }
+ ]
+ },
matchDescription: {
format: 'regex',
type: 'string'
},
+ noDefaults: {
+ default: false,
+ type: 'boolean'
+ },
tags: {
patternProperties: {
'.*': {
@@ -68,7 +91,6 @@ export default iterateJsdoc(({
type: 'string'
},
{
- enum: [true],
type: 'boolean'
}
]
diff --git a/test/rules/assertions/matchDescription.js b/test/rules/assertions/matchDescription.js
index f334e4b88..efef972bf 100644
--- a/test/rules/assertions/matchDescription.js
+++ b/test/rules/assertions/matchDescription.js
@@ -11,6 +11,7 @@ export default {
`,
errors: [
{
+ line: 3,
message: 'JSDoc description does not satisfy the regex pattern.'
}
]
@@ -26,6 +27,7 @@ export default {
`,
errors: [
{
+ line: 3,
message: 'JSDoc description does not satisfy the regex pattern.'
}
]
@@ -41,6 +43,7 @@ export default {
`,
errors: [
{
+ line: 3,
message: 'JSDoc description does not satisfy the regex pattern.'
}
],
@@ -48,6 +51,28 @@ export default {
matchDescription: '[\u0410-\u042F][\u0410-\u044F]+\\.'
}]
},
+ {
+ code: `
+ /**
+ * Abc.
+ */
+ function quux () {
+
+ }
+ `,
+ errors: [
+ {
+ line: 3,
+ message: 'JSDoc description does not satisfy the regex pattern.'
+ }
+ ],
+ options: [{
+ tags: {
+ 'main description': '[\u0410-\u042F][\u0410-\u044F]+\\.',
+ param: true
+ }
+ }]
+ },
{
code: `
/**
@@ -59,6 +84,7 @@ export default {
`,
errors: [
{
+ line: 3,
message: 'JSDoc description does not satisfy the regex pattern.'
}
]
@@ -76,6 +102,7 @@ export default {
`,
errors: [
{
+ line: 5,
message: 'JSDoc description does not satisfy the regex pattern.'
}
],
@@ -87,6 +114,58 @@ export default {
}
]
},
+ {
+ code: `
+ /**
+ * Foo
+ *
+ * @param foo foo.
+ */
+ function quux (foo) {
+
+ }
+ `,
+ errors: [
+ {
+ line: 5,
+ message: 'JSDoc description does not satisfy the regex pattern.'
+ }
+ ],
+ options: [
+ {
+ tags: {
+ 'main description': '^[a-zA-Z]*$',
+ param: true
+ }
+ }
+ ]
+ },
+ {
+ code: `
+ /**
+ * Foo
+ *
+ * @param foo foo.
+ */
+ function quux (foo) {
+
+ }
+ `,
+ errors: [
+ {
+ line: 5,
+ message: 'JSDoc description does not satisfy the regex pattern.'
+ }
+ ],
+ options: [
+ {
+ tags: {
+ 'main description': false,
+ param: true
+ }
+ }
+ ]
+ },
{
code: `
/**
@@ -100,6 +179,7 @@ export default {
`,
errors: [
{
+ line: 5,
message: 'JSDoc description does not satisfy the regex pattern.'
}
],
@@ -122,6 +202,7 @@ export default {
`,
errors: [
{
+ line: 3,
message: 'JSDoc description does not satisfy the regex pattern.'
}
]
@@ -139,6 +220,7 @@ export default {
`,
errors: [
{
+ line: 5,
message: 'JSDoc description does not satisfy the regex pattern.'
}
],
@@ -163,6 +245,7 @@ export default {
`,
errors: [
{
+ line: 5,
message: 'JSDoc description does not satisfy the regex pattern.'
}
],
@@ -190,6 +273,7 @@ export default {
`,
errors: [
{
+ line: 3,
message: 'JSDoc description does not satisfy the regex pattern.'
}
]
@@ -205,6 +289,7 @@ export default {
`,
errors: [
{
+ line: 3,
message: 'JSDoc description does not satisfy the regex pattern.'
}
],
@@ -227,6 +312,7 @@ export default {
`,
errors: [
{
+ line: 3,
message: 'JSDoc description does not satisfy the regex pattern.'
}
],
@@ -249,6 +335,7 @@ export default {
`,
errors: [
{
+ line: 3,
message: 'JSDoc description does not satisfy the regex pattern.'
}
],
@@ -273,6 +360,7 @@ export default {
`,
errors: [
{
+ line: 5,
message: 'JSDoc description does not satisfy the regex pattern.'
}
],
@@ -296,6 +384,7 @@ export default {
`,
errors: [
{
+ line: 3,
message: 'JSDoc description does not satisfy the regex pattern.'
}
],
@@ -304,6 +393,30 @@ export default {
param: '[\u0410-\u042F][\u0410-\u044F]+\\.'
}
}]
+ },
+ {
+ code: `
+ /**
+ * foo.
+ */
+ class quux {
+
+ }
+ `,
+ errors: [
+ {
+ line: 3,
+ message: 'JSDoc description does not satisfy the regex pattern.'
+ }
+ ],
+ options: [
+ {
+ contexts: [
+ 'ClassDeclaration'
+ ],
+ noDefaults: true
+ }
+ ]
}
],
valid: [
@@ -493,6 +606,52 @@ export default {
}
`
+ },
+ {
+ code: `
+ /**
+ * foo.
+ */
+ function quux () {
+
+ }
+ `,
+ options: [
+ {tags: {
+ 'main description': false
+ }}
+ ]
+ },
+ {
+ code: `
+ /**
+ * foo.
+ */
+ class quux {
+
+ }
+ `,
+ errors: [
+ {
+ line: 3,
+ message: 'JSDoc description does not satisfy the regex pattern.'
+ }
+ ]
+ },
+ {
+ code: `
+ /**
+ * foo.
+ */
+ class quux {
+
+ }
+ `,
+ options: [
+ {tags: {
+ 'main description': true
+ }}
+ ]
}
]
};