docs: indicate option defaults (fixes part of #256) and ensure optioins all listed in docs

Author: brettz9

.README/rules/check-types.md

@@ -24,7 +24,7 @@ RegExp
 - An option object:
   - with the key `noDefaults` to insist that only the supplied option type
     map is to be used, and that the default preferences (such as "string"
-    over "String") will not be enforced.
+    over "String") will not be enforced. The option's default is `false`.
   - with the key `unifyParentAndChildTypeChecks` which will treat
     `settings.jsdoc.preferredTypes` keys such as `SomeType` as matching
     not only child types such as an unadorned `SomeType` but also

.README/rules/match-description.md

@@ -50,6 +50,8 @@ tag should be linted with the `matchDescription` value (or the default).
 }
 ```
 
+##### `mainDescription`
+
 If you wish to override the main function description without changing the
 default `match-description`, you may use `mainDescription`:
 
@@ -73,13 +75,13 @@ it by setting it to `false`.
 
 Set this to an array of strings representing the AST context
 where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
-Overrides the defaults.
+Overrides the default contexts (see below).
 
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|N/A by default but see `tags` options|
 |Settings||
-|Options|`contexts`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
+|Options|`contexts`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `mainDescription`, `matchDescription`|
 
 <!-- assertions matchDescription -->

.README/rules/newline-after-description.md

@@ -2,11 +2,14 @@
 
 Enforces a consistent padding of the block description.
 
-This rule takes one argument. If it is `"always"` then a problem is raised when there is a newline after the description. If it is `"never"` then a problem is raised when there is no newline after the description. The default value is `"always"`.
+#### Options
+
+This rule allows one optional string argument. If it is `"always"` then a problem is raised when there is a newline after the description. If it is `"never"` then a problem is raised when there is no newline after the description. The default value is `"always"`.
 
 |||
 |---|---|
 |Context|everywhere|
+|Options|(a string matching `"always"|"never"`)|
 |Tags|N/A|
 
 <!-- assertions newlineAfterDescription -->

.README/rules/no-undefined-types.md

@@ -26,9 +26,10 @@ An option object may have the following keys:
 
 - `preferredTypesDefined` -  If this option is set to `true` and preferred
   types are indicated within `settings.jsdoc.preferredTypes`, any such
-  types will be assumed to be defined as well.
+  types will be assumed to be defined as well. Defaults to `false`.
 - `definedTypes` - This array can be populated to indicate other types which
-  are automatically considered as defined (in addition to globals, etc.)
+  are automatically considered as defined (in addition to globals, etc.).
+  Defaults to an empty array.
 
 |||
 |---|---|

.README/rules/require-description.md

@@ -11,9 +11,9 @@ An options object may have any of the following properties:
 
 - `contexts` - Set to an array of strings representing the AST context
   where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
-  Overrides the defaults.
+  Overrides the default contexts (see below).
 - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
-    block avoids the need for a `@description`.
+    block avoids the need for a `@description`. Defaults to an empty array.
 
 |||
 |---|---|

.README/rules/require-example.md

@@ -10,7 +10,7 @@ Requires that all functions have examples.
 Has an object option with one optional property:
 
 - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
-  block avoids the need for an `@example`.
+  block avoids the need for an `@example`. Defaults to an empty array.
 
 |||
 |---|---|

.README/rules/require-hyphen-before-param-description.md

@@ -2,12 +2,15 @@
 
 Requires a hyphen before the `@param` description.
 
-This rule takes one argument. If it is `"always"` then a problem is raised when there is no hyphen before the description. If it is `"never"` then a problem is raised when there is a hyphen before the description. The default value is `"always"`.
+#### Options
+
+This rule takes one optional string argument. If it is `"always"` then a problem is raised when there is no hyphen before the description. If it is `"never"` then a problem is raised when there is a hyphen before the description. The default value is `"always"`.
 
 |||
 |---|---|
 |Context|everywhere|
 |Tags|`param`|
 |Aliases|`arg`, `argument`|
+|Options|(a string matching `"always"|"never"`)|
 
 <!-- assertions requireHyphenBeforeParamDescription -->

.README/rules/require-jsdoc.md

@@ -5,16 +5,13 @@ functions.
 
 #### Options
 
-Accepts one optional options object, with two optional keys, `publicOnly`
-for confining JSDoc comments to be checked to exported functions (with "exported"
-allowing for ESM exports, CJS exports, or browser window global export)
-in `require-jsdoc`, and `require` for limiting the contexts which are to
-be checked by the rule.
+Accepts one optional options object with the following optional keys.
 
-- `publicOnly` - Missing jsdoc blocks are only reported for function
-  bodies / class declarations that are exported from the module.
-  May be a boolean or object. If set to `true`, the defaults below will
-  be used.
+- `publicOnly` - This option will insist that missing jsdoc blocks are
+  only reported for function bodies / class declarations that are exported
+  from the module. May be a boolean or object. If set to `true`, the defaults
+  below will be used. If unset, jsdoc block reporting will not be limited to
+  exports.
 
   This object supports the following optional boolean keys (`false` unless
   otherwise noted):
@@ -25,7 +22,8 @@ be checked by the rule.
   - `window` - Window global exports are checked for JSDoc comments
 
 - `require` - An object with the following optional boolean keys which all
-    default to `false` except as noted:
+    default to `false` except as noted, indicating the contexts where the rule
+    will apply:
 
   - `ArrowFunctionExpression`
   - `ClassDeclaration`
@@ -35,13 +33,14 @@ be checked by the rule.
   - `MethodDefinition`
 
 - `contexts` - Set this to an array of strings representing the additional
-  AST context where you wish the rule to be applied (e.g., `Property` for properties).
+  AST contexts where you wish the rule to be applied (e.g., `Property` for
+  properties). Defaults to an empty array.
 
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `ClassDeclaration`, `ClassExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|N/A|
-|Options|`publicOnly`|
+|Options|`publicOnly`, `require`, `contexts`|
 |Settings|`exemptEmptyFunctions`|
 
 <!-- assertions requireJsdoc -->

.README/rules/require-param.md

@@ -7,7 +7,7 @@ Requires that all function parameters are documented.
 An options object accepts one optional property:
 
 - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
-    block avoids the need for a `@param`.
+    block avoids the need for a `@param`. Defaults to an empty array.
 
 |||
 |---|---|

.README/rules/require-returns.md

@@ -5,8 +5,8 @@ Requires returns are documented.
 #### Options
 
 - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
-    block avoids the need for a `@returns`.
-- `forceReturnsWithAsync` - By default `async` functions that do not explicitly return a value pass this rule. You can force all `async` functions to require return statements by setting `forceReturnsWithAsync` as true on the options object. This may be useful as an `async` function will always return a Promise, even if the Promise returns void.
+    block avoids the need for a `@returns`. Defaults to an empty array.
+- `forceReturnsWithAsync` - By default `async` functions that do not explicitly return a value pass this rule. You can force all `async` functions to require return statements by setting `forceReturnsWithAsync` to `true` on the options object. This may be useful as an `async` function will always return a `Promise`, even if the `Promise` returns void. Defaults to `false`.
 
 ```js
 'jsdoc/require-jsdoc': ['error', {forceReturnsWithAsync: true}]