eslint-plugin-jsdoc 39.0.0 → 39.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +15 -1
- package/README.md +31 -6
- package/dist/rules/requireExample.js +8 -1
- package/dist/rules/requireExample.js.map +1 -1
- package/package.json +1 -1
package/CONTRIBUTING.md
CHANGED
|
@@ -27,7 +27,21 @@ npm run build
|
|
|
27
27
|
## Coding standards
|
|
28
28
|
|
|
29
29
|
The project follows ESLint rules from [`canonical`](https://www.npmjs.com/package/eslint-config-canonical)
|
|
30
|
-
and testing follows its subconfig, `canonical/mocha`.
|
|
30
|
+
and testing follows its subconfig, `canonical/mocha`. You can run
|
|
31
|
+
`npm run lint` to check the linting if your IDE is not already indicating
|
|
32
|
+
items needing fixing.
|
|
33
|
+
|
|
34
|
+
## Documentation building
|
|
35
|
+
|
|
36
|
+
In order to make changes that are reflected in the README, you will need to
|
|
37
|
+
modify files within the `.README` directory. `.README/README.md` contains the
|
|
38
|
+
main README skeleton and details on the project, its global `settings`, etc.,
|
|
39
|
+
while the documentation for specific rules (that will get pulled into the
|
|
40
|
+
README) ought to be modified within the relevant file within `.README/rules`.
|
|
41
|
+
Once these files are modified, you can run `npm run create-readme` to have
|
|
42
|
+
these files integrated into the main `/README.md`. While you should include
|
|
43
|
+
the built file in your PR, you will do not want to make manual changes
|
|
44
|
+
directly to this file as they will be overwritten.
|
|
31
45
|
|
|
32
46
|
## Testing
|
|
33
47
|
|
package/README.md
CHANGED
|
@@ -198,7 +198,7 @@ object supplied as the second argument in an array after the error level
|
|
|
198
198
|
// The options vary by rule, but are generally added to an options
|
|
199
199
|
// object as follows:
|
|
200
200
|
{
|
|
201
|
-
|
|
201
|
+
checkConstructors: true,
|
|
202
202
|
exemptedBy: ['type']
|
|
203
203
|
}
|
|
204
204
|
]
|
|
@@ -11939,6 +11939,13 @@ A value indicating whether getters should be checked. Defaults to `false`.
|
|
|
11939
11939
|
|
|
11940
11940
|
A value indicating whether setters should be checked. Defaults to `false`.
|
|
11941
11941
|
|
|
11942
|
+
<a name="user-content-eslint-plugin-jsdoc-rules-require-example-options-25-enablefixer-2"></a>
|
|
11943
|
+
<a name="eslint-plugin-jsdoc-rules-require-example-options-25-enablefixer-2"></a>
|
|
11944
|
+
##### <code>enableFixer</code>
|
|
11945
|
+
|
|
11946
|
+
A boolean on whether to enable the fixer (which adds an empty `@example` block).
|
|
11947
|
+
Defaults to `true`.
|
|
11948
|
+
|
|
11942
11949
|
<a name="user-content-eslint-plugin-jsdoc-rules-require-example-fixer"></a>
|
|
11943
11950
|
<a name="eslint-plugin-jsdoc-rules-require-example-fixer"></a>
|
|
11944
11951
|
#### Fixer
|
|
@@ -11951,7 +11958,7 @@ report a missing example description after this is added.
|
|
|
11951
11958
|
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
|
|
11952
11959
|
|Tags|`example`|
|
|
11953
11960
|
|Recommended|false|
|
|
11954
|
-
|Options|`exemptedBy`, `exemptNoArguments`, `
|
|
11961
|
+
|Options|`exemptedBy`, `exemptNoArguments`, `contexts`, `checkConstructors`, `checkGetters`, `checkSetters`, `enableFixer`|
|
|
11955
11962
|
|Settings|`ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
|
|
11956
11963
|
|
|
11957
11964
|
The following patterns are considered problems:
|
|
@@ -12065,6 +12072,24 @@ class TestClass {
|
|
|
12065
12072
|
}
|
|
12066
12073
|
// "jsdoc/require-example": ["error"|"warn", {"checkSetters":true}]
|
|
12067
12074
|
// Message: Missing JSDoc @example description.
|
|
12075
|
+
|
|
12076
|
+
/**
|
|
12077
|
+
*
|
|
12078
|
+
*/
|
|
12079
|
+
function quux (someParam) {
|
|
12080
|
+
|
|
12081
|
+
}
|
|
12082
|
+
// "jsdoc/require-example": ["error"|"warn", {"enableFixer":true}]
|
|
12083
|
+
// Message: Missing JSDoc @example declaration.
|
|
12084
|
+
|
|
12085
|
+
/**
|
|
12086
|
+
*
|
|
12087
|
+
*/
|
|
12088
|
+
function quux (someParam) {
|
|
12089
|
+
|
|
12090
|
+
}
|
|
12091
|
+
// "jsdoc/require-example": ["error"|"warn", {"enableFixer":false}]
|
|
12092
|
+
// Message: Missing JSDoc @example declaration.
|
|
12068
12093
|
````
|
|
12069
12094
|
|
|
12070
12095
|
The following patterns are not considered problems:
|
|
@@ -12852,8 +12877,8 @@ setters should be checked but only when there is no getter. This may be useful
|
|
|
12852
12877
|
if one only wishes documentation on one of the two accessors. Defaults to
|
|
12853
12878
|
`false`.
|
|
12854
12879
|
|
|
12855
|
-
<a name="user-content-eslint-plugin-jsdoc-rules-require-jsdoc-options-28-enablefixer-
|
|
12856
|
-
<a name="eslint-plugin-jsdoc-rules-require-jsdoc-options-28-enablefixer-
|
|
12880
|
+
<a name="user-content-eslint-plugin-jsdoc-rules-require-jsdoc-options-28-enablefixer-3"></a>
|
|
12881
|
+
<a name="eslint-plugin-jsdoc-rules-require-jsdoc-options-28-enablefixer-3"></a>
|
|
12857
12882
|
##### <code>enableFixer</code>
|
|
12858
12883
|
|
|
12859
12884
|
A boolean on whether to enable the fixer (which adds an empty jsdoc block).
|
|
@@ -15030,8 +15055,8 @@ function signature, it may appear that there is an actual property named
|
|
|
15030
15055
|
|
|
15031
15056
|
An options object accepts the following optional properties:
|
|
15032
15057
|
|
|
15033
|
-
<a name="user-content-eslint-plugin-jsdoc-rules-require-param-options-32-enablefixer-
|
|
15034
|
-
<a name="eslint-plugin-jsdoc-rules-require-param-options-32-enablefixer-
|
|
15058
|
+
<a name="user-content-eslint-plugin-jsdoc-rules-require-param-options-32-enablefixer-4"></a>
|
|
15059
|
+
<a name="eslint-plugin-jsdoc-rules-require-param-options-32-enablefixer-4"></a>
|
|
15035
15060
|
##### <code>enableFixer</code>
|
|
15036
15061
|
|
|
15037
15062
|
Whether to enable the fixer. Defaults to `true`.
|
|
@@ -20,6 +20,7 @@ var _default = (0, _iterateJsdoc.default)(({
|
|
|
20
20
|
}
|
|
21
21
|
|
|
22
22
|
const {
|
|
23
|
+
enableFixer = true,
|
|
23
24
|
exemptNoArguments = false
|
|
24
25
|
} = context.options[0] || {};
|
|
25
26
|
const targetTagName = 'example';
|
|
@@ -35,7 +36,9 @@ var _default = (0, _iterateJsdoc.default)(({
|
|
|
35
36
|
}
|
|
36
37
|
|
|
37
38
|
utils.reportJSDoc(`Missing JSDoc @${targetTagName} declaration.`, null, () => {
|
|
38
|
-
|
|
39
|
+
if (enableFixer) {
|
|
40
|
+
utils.addTag(targetTagName);
|
|
41
|
+
}
|
|
39
42
|
});
|
|
40
43
|
return;
|
|
41
44
|
}
|
|
@@ -89,6 +92,10 @@ var _default = (0, _iterateJsdoc.default)(({
|
|
|
89
92
|
},
|
|
90
93
|
type: 'array'
|
|
91
94
|
},
|
|
95
|
+
enableFixer: {
|
|
96
|
+
default: true,
|
|
97
|
+
type: 'boolean'
|
|
98
|
+
},
|
|
92
99
|
exemptedBy: {
|
|
93
100
|
items: {
|
|
94
101
|
type: 'string'
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/rules/requireExample.js"],"names":["context","jsdoc","report","utils","avoidDocs","exemptNoArguments","options","targetTagName","functionExamples","tags","filter","tag","length","isIteratingFunction","hasParams","reportJSDoc","addTag","example","exampleContent","name","getTagDescription","trim","split","Boolean","contextDefaults","meta","docs","description","url","fixable","schema","additionalProperties","properties","checkConstructors","default","type","checkGetters","checkSetters","contexts","items","anyOf","comment","exemptedBy"],"mappings":";;;;;;;AAAA;;;;eAEe,2BAAa,CAAC;AAC3BA,EAAAA,OAD2B;AAE3BC,EAAAA,KAF2B;AAG3BC,EAAAA,MAH2B;AAI3BC,EAAAA;AAJ2B,CAAD,KAKtB;AACJ,MAAIA,KAAK,CAACC,SAAN,EAAJ,EAAuB;AACrB;AACD;;AAED,QAAM;AACJC,IAAAA,iBAAiB,GAAG;
|
|
1
|
+
{"version":3,"sources":["../../src/rules/requireExample.js"],"names":["context","jsdoc","report","utils","avoidDocs","enableFixer","exemptNoArguments","options","targetTagName","functionExamples","tags","filter","tag","length","isIteratingFunction","hasParams","reportJSDoc","addTag","example","exampleContent","name","getTagDescription","trim","split","Boolean","contextDefaults","meta","docs","description","url","fixable","schema","additionalProperties","properties","checkConstructors","default","type","checkGetters","checkSetters","contexts","items","anyOf","comment","exemptedBy"],"mappings":"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","sourcesContent":["import iterateJsdoc from '../iterateJsdoc';\n\nexport default iterateJsdoc(({\n context,\n jsdoc,\n report,\n utils,\n}) => {\n if (utils.avoidDocs()) {\n return;\n }\n\n const {\n enableFixer = true,\n exemptNoArguments = false,\n } = context.options[0] || {};\n\n const targetTagName = 'example';\n\n const functionExamples = jsdoc.tags.filter(({\n tag,\n }) => {\n return tag === targetTagName;\n });\n\n if (!functionExamples.length) {\n if (exemptNoArguments && utils.isIteratingFunction() &&\n !utils.hasParams()\n ) {\n return;\n }\n\n utils.reportJSDoc(`Missing JSDoc @${targetTagName} declaration.`, null, () => {\n if (enableFixer) {\n utils.addTag(targetTagName);\n }\n });\n\n return;\n }\n\n for (const example of functionExamples) {\n const exampleContent = `${example.name} ${utils.getTagDescription(example)}`\n .trim()\n .split('\\n')\n .filter(Boolean);\n\n if (!exampleContent.length) {\n report(`Missing JSDoc @${targetTagName} description.`, null, example);\n }\n }\n}, {\n contextDefaults: true,\n meta: {\n docs: {\n description: 'Requires that all functions have examples.',\n url: 'https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-example',\n },\n fixable: 'code',\n schema: [\n {\n additionalProperties: false,\n properties: {\n checkConstructors: {\n default: true,\n type: 'boolean',\n },\n checkGetters: {\n default: false,\n type: 'boolean',\n },\n checkSetters: {\n default: false,\n type: 'boolean',\n },\n contexts: {\n items: {\n anyOf: [\n {\n type: 'string',\n },\n {\n additionalProperties: false,\n properties: {\n comment: {\n type: 'string',\n },\n context: {\n type: 'string',\n },\n },\n type: 'object',\n },\n ],\n },\n type: 'array',\n },\n enableFixer: {\n default: true,\n type: 'boolean',\n },\n exemptedBy: {\n items: {\n type: 'string',\n },\n type: 'array',\n },\n exemptNoArguments: {\n default: false,\n type: 'boolean',\n },\n },\n type: 'object',\n },\n ],\n type: 'suggestion',\n },\n});\n"],"file":"requireExample.js"}
|
package/package.json
CHANGED