feat: add allowInlineConfig and reportUnusedDisableDirectives (#126)

Author: brettz9

.README/README.md

@@ -158,7 +158,7 @@ The format of the configuration is as follows:
 ### Settings to Configure `check-examples`
 
 The settings below all impact the `check-examples` rule and default to
-no-op/false except for `eslintrcForExamples` which defaults to `true`.
+no-op/false except as noted.
 
 JSDoc specs use of an optional `<caption>` element at the beginning of
 `@example`. The following setting requires its use.
@@ -192,6 +192,9 @@ applied to the JavaScript found within the `@example` tags (as determined
 to be applicable by the above regex settings). They are ordered by
 decreasing precedence:
 
+* `settings.jsdoc.allowInlineConfig` - If not set to `false`, will allow
+  inline config within the `@example` to override other config. Defaults
+  to `true`.
 * `settings.jsdoc.noDefaultExampleRules` - Setting to `true` will disable the
   default rules which are expected to be troublesome for most documentation
   use. See the section below for the specific default rules.
@@ -204,13 +207,20 @@ decreasing precedence:
   [other plugins](https://github.com/eslint/eslint-plugin-markdown), e.g.,
   if one sets `matchingFileName` to `dummy.md` so that `@example` rules will
   follow one's Markdown rules).
-* `settings.jsdoc.configFile` - A config file. Corresponds to `-c`.
+* `settings.jsdoc.configFile` - A config file. Corresponds to ESLint's `-c`.
 * `settings.jsdoc.eslintrcForExamples` - Defaults to `true` in adding rules
   based on an `.eslintrc.*` file. Setting to `false` corresponds to
-  `--no-eslintrc`.
+  ESLint's `--no-eslintrc`.
 * `settings.jsdoc.baseConfig` - An object of rules with the same schema
   as `.eslintrc.*` for defaults
 
+Finally, the following rule pertains to inline disable directives:
+
+- `settings.jsdoc.reportUnusedDisableDirectives` - If not set to `false`,
+  this will report disabled directives which are not used (and thus not
+  needed). Defaults to `true`. Corresponds to ESLint's
+  `--report-unused-disable-directives`.
+
 #### Rules Disabled by Default Unless `noDefaultExampleRules` is Set to `true`
 
 * `eol-last` - Insisting that a newline "always" be at the end is less likely

.README/rules/check-examples.md

@@ -7,11 +7,13 @@ Works in conjunction with the following settings:
 * `captionRequired`
 * `exampleCodeRegex`
 * `rejectExampleCodeRegex`
+* `allowInlineConfig` - Defaults to `true`
 * `noDefaultExampleRules`
 * `matchingFileName`
 * `configFile`
 * `eslintrcForExamples` - Defaults to `true`
 * `baseConfig`
+* `reportUnusedDisableDirectives` - Defaults to `true`
 
 Inline ESLint config within `@example` JavaScript is allowed, though the
 disabling of ESLint directives which are not needed by the resolved rules

README.md

@@ -782,7 +782,7 @@ function quux (foo) {
 }
 // Settings: {"jsdoc":{"additionalTagNames":{"customTags":["baz","bar"]}}}
 
-/** 
+/**
  * @abstract
  * @access
  * @alias
@@ -870,9 +870,9 @@ RegExp
 <a name="eslint-plugin-jsdoc-rules-check-types-why-not-capital-case-everything"></a>
 #### Why not capital case everything?
 
-Why are `boolean`, `number` and `string` exempt from starting with a capital letter? Let's take `string` as an example. In Javascript, everything is an object. The string Object has prototypes for string functions such as `.toUpperCase()`. 
+Why are `boolean`, `number` and `string` exempt from starting with a capital letter? Let's take `string` as an example. In Javascript, everything is an object. The string Object has prototypes for string functions such as `.toUpperCase()`.
 
-Fortunately we don't have to write `new String()` everywhere in our code. Javascript will automatically wrap string primitives into string Objects when we're applying a string function to a string primitive. This way the memory footprint is a tiny little bit smaller, and the [GC](https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)) has less work to do. 
+Fortunately we don't have to write `new String()` everywhere in our code. Javascript will automatically wrap string primitives into string Objects when we're applying a string function to a string primitive. This way the memory footprint is a tiny little bit smaller, and the [GC](https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)) has less work to do.
 
 So in a sense, there two types of strings in Javascript; `{string}` literals, also called primitives and `{String}` Objects. We use the primitives because it's easier to write and uses less memory. `{String}` and `{string}` are technically both valid, but they are not the same.
 
@@ -2190,5 +2190,3 @@ function quux() {
 
 }
 ```
-
-

src/iterateJsdoc.js

@@ -33,6 +33,8 @@ const curryUtils = (
   captionRequired,
   matchingFileName,
   eslintrcForExamples,
+  allowInlineConfig,
+  reportUnusedDisableDirectives,
   noDefaultExampleRules,
   allowOverrideWithoutParam,
   allowImplementsWithoutParam,
@@ -82,6 +84,14 @@ const curryUtils = (
     return eslintrcForExamples;
   };
 
+  utils.allowInlineConfig = () => {
+    return allowInlineConfig;
+  };
+
+  utils.reportUnusedDisableDirectives = () => {
+    return reportUnusedDisableDirectives;
+  };
+
   utils.hasNoDefaultExampleRules = () => {
     return noDefaultExampleRules;
   };
@@ -148,6 +158,8 @@ export default (iterator) => {
     const baseConfig = _.get(context, 'settings.jsdoc.baseConfig') || {};
     const configFile = _.get(context, 'settings.jsdoc.configFile');
     const eslintrcForExamples = _.get(context, 'settings.jsdoc.eslintrcForExamples') !== false;
+    const allowInlineConfig = _.get(context, 'settings.jsdoc.allowInlineConfig') !== false;
+    const reportUnusedDisableDirectives = _.get(context, 'settings.jsdoc.reportUnusedDisableDirectives') !== false;
     const captionRequired = Boolean(_.get(context, 'settings.jsdoc.captionRequired'));
     const noDefaultExampleRules = Boolean(_.get(context, 'settings.jsdoc.noDefaultExampleRules'));
     const allowOverrideWithoutParam = Boolean(_.get(context, 'settings.jsdoc.allowOverrideWithoutParam'));
@@ -212,6 +224,8 @@ export default (iterator) => {
         captionRequired,
         matchingFileName,
         eslintrcForExamples,
+        allowInlineConfig,
+        reportUnusedDisableDirectives,
         noDefaultExampleRules,
         allowOverrideWithoutParam,
         allowImplementsWithoutParam,

src/rules/checkExamples.js

@@ -26,10 +26,10 @@ export default iterateJsdoc(({
   const filename = utils.getMatchingFileName();
   const baseConfig = utils.getBaseConfig();
   const configFile = utils.getConfigFile();
+  const allowInlineConfig = utils.allowInlineConfig();
+  const reportUnusedDisableDirectives = utils.reportUnusedDisableDirectives();
 
-  // Make these configurable?
-  const reportUnusedDisableDirectives = true;
-  const allowInlineConfig = true;
+  // Make this configurable?
   const rulePaths = [];
 
   const rules = noDefaultExampleRules ? undefined : {

test/rules/assertions/checkExamples.js

@@ -137,7 +137,6 @@ export default {
         }
       }
     },
-
     {
       code: `
           /**
@@ -209,6 +208,44 @@ export default {
           noDefaultExampleRules: false
         }
       }
+    },
+    {
+      code: `
+      /**
+       * @example test() // eslint-disable-line semi
+       */
+      function quux () {}
+`,
+      errors: ['@example error: Unused eslint-disable directive (no problems were reported from \'semi\').'],
+      settings: {
+        jsdoc: {
+          eslintrcForExamples: false,
+          noDefaultExampleRules: true,
+          reportUnusedDisableDirectives: true
+        }
+      }
+    },
+    {
+      code: `
+      /**
+       * @example
+       test() // eslint-disable-line semi
+       */
+      function quux () {}
+`,
+      errors: ['@example error (semi): Missing semicolon.'],
+      settings: {
+        jsdoc: {
+          allowInlineConfig: false,
+          baseConfig: {
+            rules: {
+              semi: ['error', 'always']
+            }
+          },
+          eslintrcForExamples: false,
+          noDefaultExampleRules: true
+        }
+      }
     }
   ],
   valid: [
@@ -313,6 +350,42 @@ export default {
           eslintrcForExamples: false
         }
       }
+    },
+    {
+      code: `
+      /**
+       * @example test() // eslint-disable-line semi
+       */
+      function quux () {}
+`,
+      settings: {
+        jsdoc: {
+          eslintrcForExamples: false,
+          noDefaultExampleRules: true,
+          reportUnusedDisableDirectives: false
+        }
+      }
+    },
+    {
+      code: `
+      /**
+       * @example
+       test() // eslint-disable-line semi
+       */
+      function quux () {}
+`,
+      settings: {
+        jsdoc: {
+          allowInlineConfig: true,
+          baseConfig: {
+            rules: {
+              semi: ['error', 'always']
+            }
+          },
+          eslintrcForExamples: false,
+          noDefaultExampleRules: true
+        }
+      }
     }
   ]
 };