feat(check-examples): add options checkDefaults, checkParams, `…

…checkProperties`; fixes #473

.README/rules/check-examples.md

@@ -1,6 +1,8 @@
 ### `check-examples`
 
-Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules.
+Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules. Also
+has options to lint the default values of optional `@param`/`@arg`/`@argument`
+and `@property`/`@prop` tags or the values of `@default`/`@defaultvalue` tags.
 
 #### Options
 
@@ -14,6 +16,8 @@ JSDoc specs use of an optional `<caption>` element at the beginning of
 The option `captionRequired` insists on a `<caption>` being present at
 the beginning of any `@example`.
 
+Used only for `@example`.
+
 ##### `exampleCodeRegex` and `rejectExampleCodeRegex`
 
 JSDoc does not specify a formal means for delimiting code blocks within
@@ -55,28 +59,31 @@ out before evaluation.
 /**
  * @example
  *     anArray.filter((a) => {
- *      return a.b;
+ *       return a.b;
  *     });
  */
 ```
 
+Only applied to `@example` linting.
+
 ##### `reportUnusedDisableDirectives`
 
 If not set to `false`, `reportUnusedDisableDirectives` will report disabled
 directives which are not used (and thus not needed). Defaults to `true`.
 Corresponds to ESLint's [`--report-unused-disable-directives`](https://eslint.org/docs/user-guide/command-line-interface#--report-unused-disable-directives).
 
-Inline ESLint config within `@example` JavaScript is allowed, though the
-disabling of ESLint directives which are not needed by the resolved rules
-will be reported as with the ESLint `--report-unused-disable-directives`
-command.
+Inline ESLint config within `@example` JavaScript is allowed (or within
+`@default`, etc.), though the disabling of ESLint directives which are not
+needed by the resolved rules will be reported as with the ESLint
+`--report-unused-disable-directives` command.
 
 #### Options for Determining ESLint Rule Applicability (`allowInlineConfig`, `noDefaultExampleRules`, `matchingFileName`, `configFile`, `checkEslintrc`, and `baseConfig`)
 
 The following options determine which individual ESLint rules will be
 applied to the JavaScript found within the `@example` tags (as determined
-to be applicable by the above regex options). They are ordered by
-decreasing precedence:
+to be applicable by the above regex options) or for the other tags checked by
+`checkDefaults`, `checkParams`, or `checkProperties` options. They are ordered
+by decreasing precedence:
 
 * `allowInlineConfig` - If not set to `false`, will allow
   inline config within the `@example` to override other config. Defaults
@@ -136,6 +143,12 @@ decreasing precedence:
 * `node/no-missing-import` - See `import/no-unresolved`.
 * `node/no-missing-require` -  See `import/no-unresolved`.
 
+##### Options for checking other than `@example` (`checkDefaults`, `checkParams`, or `checkProperties`)
+
+* `checkDefaults` - Whether to check the values of `@default`/`@defaultvalue` tags
+* `checkParams` - Whether to check `@param`/`@arg`/`@argument` default values
+* `checkProperties` - Whether to check `@property`/`@prop` default values
+
 |||
 |---|---|
 |Context|everywhere|

README.md

@@ -868,7 +868,9 @@ function quux (foo) {
 <a name="eslint-plugin-jsdoc-rules-check-examples"></a>
 ### <code>check-examples</code>
 
-Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules.
+Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules. Also
+has options to lint the default values of optional `@param`/`@arg`/`@argument`
+and `@property`/`@prop` tags or the values of `@default`/`@defaultvalue` tags.
 
 <a name="eslint-plugin-jsdoc-rules-check-examples-options-1"></a>
 #### Options
@@ -884,6 +886,8 @@ JSDoc specs use of an optional `<caption>` element at the beginning of
 The option `captionRequired` insists on a `<caption>` being present at
 the beginning of any `@example`.
 
+Used only for `@example`.
+
 <a name="eslint-plugin-jsdoc-rules-check-examples-options-1-examplecoderegex-and-rejectexamplecoderegex"></a>
 ##### <code>exampleCodeRegex</code> and <code>rejectExampleCodeRegex</code>
 
@@ -927,30 +931,33 @@ out before evaluation.
 /**
  * @example
  *     anArray.filter((a) => {
- *      return a.b;
+ *       return a.b;
  *     });
  */
 ```
 
+Only applied to `@example` linting.
+
 <a name="eslint-plugin-jsdoc-rules-check-examples-options-1-reportunuseddisabledirectives"></a>
 ##### <code>reportUnusedDisableDirectives</code>
 
 If not set to `false`, `reportUnusedDisableDirectives` will report disabled
 directives which are not used (and thus not needed). Defaults to `true`.
 Corresponds to ESLint's [`--report-unused-disable-directives`](https://eslint.org/docs/user-guide/command-line-interface#--report-unused-disable-directives).
 
-Inline ESLint config within `@example` JavaScript is allowed, though the
-disabling of ESLint directives which are not needed by the resolved rules
-will be reported as with the ESLint `--report-unused-disable-directives`
-command.
+Inline ESLint config within `@example` JavaScript is allowed (or within
+`@default`, etc.), though the disabling of ESLint directives which are not
+needed by the resolved rules will be reported as with the ESLint
+`--report-unused-disable-directives` command.
 
 <a name="eslint-plugin-jsdoc-rules-check-examples-options-for-determining-eslint-rule-applicability-allowinlineconfig-nodefaultexamplerules-matchingfilename-configfile-checkeslintrc-and-baseconfig"></a>
 #### Options for Determining ESLint Rule Applicability (<code>allowInlineConfig</code>, <code>noDefaultExampleRules</code>, <code>matchingFileName</code>, <code>configFile</code>, <code>checkEslintrc</code>, and <code>baseConfig</code>)
 
 The following options determine which individual ESLint rules will be
 applied to the JavaScript found within the `@example` tags (as determined
-to be applicable by the above regex options). They are ordered by
-decreasing precedence:
+to be applicable by the above regex options) or for the other tags checked by
+`checkDefaults`, `checkParams`, or `checkProperties` options. They are ordered
+by decreasing precedence:
 
 * `allowInlineConfig` - If not set to `false`, will allow
   inline config within the `@example` to override other config. Defaults
@@ -1011,6 +1018,13 @@ decreasing precedence:
 * `node/no-missing-import` - See `import/no-unresolved`.
 * `node/no-missing-require` -  See `import/no-unresolved`.
 
+<a name="eslint-plugin-jsdoc-rules-check-examples-options-for-determining-eslint-rule-applicability-allowinlineconfig-nodefaultexamplerules-matchingfilename-configfile-checkeslintrc-and-baseconfig-options-for-checking-other-than-example-checkdefaults-checkparams-or-checkproperties"></a>
+##### Options for checking other than <code>@example</code> (<code>checkDefaults</code>, <code>checkParams</code>, or <code>checkProperties</code>)
+
+* `checkDefaults` - Whether to check the values of `@default`/`@defaultvalue` tags
+* `checkParams` - Whether to check `@param`/`@arg`/`@argument` default values
+* `checkProperties` - Whether to check `@property`/`@prop` default values
+
 |||
 |---|---|
 |Context|everywhere|
@@ -1302,6 +1316,28 @@ function quux () {
 }
 // Options: [{"baseConfig":{"rules":{"indent":["error"]}},"checkEslintrc":false,"noDefaultExampleRules":false}]
 // Message: @example error (indent): Expected indentation of 0 spaces but found 2.
+
+/**
+ * @default 'abc'
+ */
+const str = 'abc';
+// Options: [{"checkDefaults":true}]
+// Message: @default error (semi): Missing semicolon.
+
+/**
+ * @param {myType} [name='abc']
+ */
+function quux () {
+}
+// Options: [{"checkParams":true}]
+// Message: @param error (semi): Missing semicolon.
+
+/**
+ * @property {myType} [name='abc']
+ */
+const obj = {};
+// Options: [{"checkProperties":true}]
+// Message: @property error (semi): Missing semicolon.
 ````
 
 The following patterns are not considered problems:
@@ -1449,6 +1485,44 @@ function f () {
 function quux () {
 }
 // Options: [{"baseConfig":{"plugins":["jsdoc"],"rules":{"jsdoc/require-file-overview":["error"]}},"checkEslintrc":false,"noDefaultExampleRules":false}]
+
+/**
+ * @default 'abc';
+ */
+const str = 'abc';
+// Options: [{"checkDefaults":true}]
+
+/**
+ * @param {myType} [name='abc';]
+ */
+function quux () {
+}
+// Options: [{"checkParams":true}]
+
+/**
+ * @property {myType} [name='abc';]
+ */
+const obj = {};
+// Options: [{"checkProperties":true}]
+
+/**
+ * @default 'abc'
+ */
+const str = 'abc';
+// Options: [{"checkDefaults":false}]
+
+/**
+ * @param {myType} [name='abc']
+ */
+function quux () {
+}
+// Options: [{"checkParams":false}]
+
+/**
+ * @property {myType} [name='abc']
+ */
+const obj = {};
+// Options: [{"checkProperties":false}]
 ````