Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: gajus/eslint-plugin-jsdoc
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: v39.0.0
Choose a base ref
...
head repository: gajus/eslint-plugin-jsdoc
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: v39.0.1
Choose a head ref
  • 3 commits
  • 6 files changed
  • 2 contributors

Commits on Apr 8, 2022

  1. fix: add enableFixer option to require-example 

    - Add test coverage for option
- Add option to rule
- Wrap fixer logic in a conditional
- Update readme with new option
- Fix `require-example` readme options list to match current implementation
    @arinthros @brettz9
    arinthros authored and brettz9 committed Apr 8, 2022
    Copy the full SHA
    7416331 View commit details

  2. docs: add details on documentation building

    @brettz9
    brettz9 committed Apr 8, 2022
    Copy the full SHA
    00f1856 View commit details

  3. docs: replaces deprecated option with new option

    @arinthros @brettz9
    arinthros authored and brettz9 committed Apr 8, 2022
    Copy the full SHA
    78f4a95 View commit details
Showing with 120 additions and 10 deletions.
  1. +1 −1 .README/README.md
  2. +6 −1 .README/rules/require-example.md
  3. +15 −1 CONTRIBUTING.md
  4. +31 −6 README.md
  5. +8 −1 src/rules/requireExample.js
  6. +59 −0 test/rules/assertions/requireExample.js
2 changes: 1 addition & 1 deletion .README/README.md
View file
Original file line number Diff line number Diff line change
@@ -126,7 +126,7 @@ object supplied as the second argument in an array after the error level
// The options vary by rule, but are generally added to an options
// object as follows:
{
avoidExampleOnConstructors: true,
checkConstructors: true,
exemptedBy: ['type']
}
]
7 changes: 6 additions & 1 deletion .README/rules/require-example.md
View file
Original file line number Diff line number Diff line change
@@ -47,6 +47,11 @@ A value indicating whether getters should be checked. Defaults to `false`.

A value indicating whether setters should be checked. Defaults to `false`.

##### `enableFixer`

A boolean on whether to enable the fixer (which adds an empty `@example` block).
Defaults to `true`.

#### Fixer

The fixer for `require-example` will add an empty `@example`, but it will still
@@ -57,7 +62,7 @@ report a missing example description after this is added.
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
|Tags|`example`|
|Recommended|false|
|Options|`exemptedBy`, `exemptNoArguments`, `avoidExampleOnConstructors`, `contexts`|
|Options|`exemptedBy`, `exemptNoArguments`, `contexts`, `checkConstructors`, `checkGetters`, `checkSetters`, `enableFixer`|
|Settings|`ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|

<!-- assertions requireExample -->
16 changes: 15 additions & 1 deletion CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -27,7 +27,21 @@ npm run build
## Coding standards

The project follows ESLint rules from [`canonical`](https://www.npmjs.com/package/eslint-config-canonical)
and testing follows its subconfig, `canonical/mocha`.
and testing follows its subconfig, `canonical/mocha`. You can run
`npm run lint` to check the linting if your IDE is not already indicating
items needing fixing.

## Documentation building

In order to make changes that are reflected in the README, you will need to
modify files within the `.README` directory. `.README/README.md` contains the
main README skeleton and details on the project, its global `settings`, etc.,
while the documentation for specific rules (that will get pulled into the
README) ought to be modified within the relevant file within `.README/rules`.
Once these files are modified, you can run `npm run create-readme` to have
these files integrated into the main `/README.md`. While you should include
the built file in your PR, you will do not want to make manual changes
directly to this file as they will be overwritten.

## Testing

37 changes: 31 additions & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -198,7 +198,7 @@ object supplied as the second argument in an array after the error level
// The options vary by rule, but are generally added to an options
// object as follows:
{
avoidExampleOnConstructors: true,
checkConstructors: true,
exemptedBy: ['type']
}
]
@@ -11939,6 +11939,13 @@ A value indicating whether getters should be checked. Defaults to `false`.

A value indicating whether setters should be checked. Defaults to `false`.

<a name="user-content-eslint-plugin-jsdoc-rules-require-example-options-25-enablefixer-2"></a>
<a name="eslint-plugin-jsdoc-rules-require-example-options-25-enablefixer-2"></a>
##### <code>enableFixer</code>

A boolean on whether to enable the fixer (which adds an empty `@example` block).
Defaults to `true`.

<a name="user-content-eslint-plugin-jsdoc-rules-require-example-fixer"></a>
<a name="eslint-plugin-jsdoc-rules-require-example-fixer"></a>
#### Fixer
@@ -11951,7 +11958,7 @@ report a missing example description after this is added.
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
|Tags|`example`|
|Recommended|false|
|Options|`exemptedBy`, `exemptNoArguments`, `avoidExampleOnConstructors`, `contexts`|
|Options|`exemptedBy`, `exemptNoArguments`, `contexts`, `checkConstructors`, `checkGetters`, `checkSetters`, `enableFixer`|
|Settings|`ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|

The following patterns are considered problems:
@@ -12065,6 +12072,24 @@ class TestClass {
}
// "jsdoc/require-example": ["error"|"warn", {"checkSetters":true}]
// Message: Missing JSDoc @example description.

/**
*
*/
function quux (someParam) {

}
// "jsdoc/require-example": ["error"|"warn", {"enableFixer":true}]
// Message: Missing JSDoc @example declaration.

/**
*
*/
function quux (someParam) {

}
// "jsdoc/require-example": ["error"|"warn", {"enableFixer":false}]
// Message: Missing JSDoc @example declaration.
````

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
if one only wishes documentation on one of the two accessors. Defaults to
`false`.

<a name="user-content-eslint-plugin-jsdoc-rules-require-jsdoc-options-28-enablefixer-2"></a>
<a name="eslint-plugin-jsdoc-rules-require-jsdoc-options-28-enablefixer-2"></a>
<a name="user-content-eslint-plugin-jsdoc-rules-require-jsdoc-options-28-enablefixer-3"></a>
<a name="eslint-plugin-jsdoc-rules-require-jsdoc-options-28-enablefixer-3"></a>
##### <code>enableFixer</code>

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

An options object accepts the following optional properties:

<a name="user-content-eslint-plugin-jsdoc-rules-require-param-options-32-enablefixer-3"></a>
<a name="eslint-plugin-jsdoc-rules-require-param-options-32-enablefixer-3"></a>
<a name="user-content-eslint-plugin-jsdoc-rules-require-param-options-32-enablefixer-4"></a>
<a name="eslint-plugin-jsdoc-rules-require-param-options-32-enablefixer-4"></a>
##### <code>enableFixer</code>

Whether to enable the fixer. Defaults to `true`.
9 changes: 8 additions & 1 deletion src/rules/requireExample.js
View file
Original file line number Diff line number Diff line change
@@ -11,6 +11,7 @@ export default iterateJsdoc(({
}

const {
enableFixer = true,
exemptNoArguments = false,
} = context.options[0] || {};

@@ -30,7 +31,9 @@ export default iterateJsdoc(({
}

utils.reportJSDoc(`Missing JSDoc @${targetTagName} declaration.`, null, () => {
utils.addTag(targetTagName);
if (enableFixer) {
utils.addTag(targetTagName);
}
});

return;
@@ -92,6 +95,10 @@ export default iterateJsdoc(({
},
type: 'array',
},
enableFixer: {
default: true,
type: 'boolean',
},
exemptedBy: {
items: {
type: 'string',
59 changes: 59 additions & 0 deletions test/rules/assertions/requireExample.js
View file
Original file line number Diff line number Diff line change
@@ -326,6 +326,65 @@ function quux () {
},
],
},
{
code: `
/**
*
*/
function quux (someParam) {
}
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @example declaration.',
},
],
options: [
{
enableFixer: true,
},
],
output: `
/**
*
* @example
*/
function quux (someParam) {
}
`,
},
{
code: `
/**
*
*/
function quux (someParam) {
}
`,
errors: [
{
line: 2,
message: 'Missing JSDoc @example declaration.',
},
],
options: [
{
enableFixer: false,
},
],
output: `
/**
*
*/
function quux (someParam) {
}
`,
},
],
valid: [
{