Merge pull request #317 from golopot/move-settings-to-options

Move settings to options

.README/README.md

@@ -123,12 +123,6 @@ You can then selectively add to or override the recommended rules.
 - `settings.jsdoc.ignorePrivate` - Disables all rules for the comment block
   on which it occurs.
 
-### Exempting empty functions from `require-jsdoc`
-
-- `settings.jsdoc.exemptEmptyFunctions` - Will not report missing jsdoc blocks
-  above functions/methods with no parameters or return values (intended where
-  variable names are sufficient for themselves as documentation).
-
 ### Alias Preference
 
 Use `settings.jsdoc.tagNamePreference` to configure a preferred alias name for a JSDoc tag. The format of the configuration is: `<primary tag name>: <preferred alias name>`, e.g.
@@ -321,33 +315,6 @@ how the keys of `preferredTypes` may have `<>` or `.<>` (or just `.`)
 appended and its bearing on whether types are checked as parents/children
 only (e.g., to match `Array` if the type is `Array` vs. `Array.<string>`).
 
-### Settings to Configure `valid-types`
-
-* `settings.jsdoc.allowEmptyNamepaths` - Set to `false` to disallow
-  empty name paths with `@callback`, `@event`, `@class`, `@constructor`,
-  `@constant`, `@const`, `@function`, `@func`, `@method`, `@interface`,
-  `@member`, `@var`, `@mixin`, `@namespace`, `@listens`, `@fires`,
-  or `@emits` (these might often be expected to have an accompanying
-  name path, though they have some indicative value without one; these
-  may also allow names to be defined in another manner elsewhere in
-  the block)
-* `settings.jsdoc.checkSeesForNamepaths` - Set this to `true` to insist
-  that `@see` only use name paths (the tag is normally permitted to
-  allow other text)
-
-### Settings to Configure `require-returns`
-
-* `settings.jsdoc.forceRequireReturn` - Set to `true` to always insist on
-  `@returns` documentation regardless of implicit or explicit `return`'s
-  in the function. May be desired to flag that a project is aware of an
-  `undefined`/`void` return.
-
-### Settings to Configure `require-example`
-
-* `settings.jsdoc.avoidExampleOnConstructors` - Set to `true` to avoid the
-  need for an example on a constructor (whether indicated as such by a
-  jsdoc tag or by being within an ES6 `class`).
-
 ### Settings to Configure `check-examples`
 
 The settings below all impact the `check-examples` rule and default to

.README/rules/require-example.md

@@ -7,16 +7,19 @@ Requires that all functions have examples.
 
 #### Options
 
-Has an object option with one optional property:
+This rule has an object option:
 
 - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
   block avoids the need for an `@example`. Defaults to an empty array.
 
+- `avoidExampleOnConstructors` (default: false) - Set to `true` to avoid the
+  need for an example on a constructor (whether indicated as such by a
+  jsdoc tag or by being within an ES6 `class`).
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`example`|
-|Options|`exemptedBy`|
-|Settings|`avoidExampleOnConstructors`|
+|Options|`exemptedBy`, `avoidExampleOnConstructors`|
 
 <!-- assertions requireExample -->

.README/rules/require-jsdoc.md

@@ -36,11 +36,14 @@ Accepts one optional options object with the following optional keys.
   AST contexts where you wish the rule to be applied (e.g., `Property` for
   properties). Defaults to an empty array.
 
+- `exemptEmptyFunctions` (default: false) - When `true`, the rule will not report
+  missing jsdoc blocks above functions/methods with no parameters or return values
+  (intended where variable names are sufficient for themselves as documentation).
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `ClassDeclaration`, `ClassExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|N/A|
-|Options|`publicOnly`, `require`, `contexts`|
-|Settings|`exemptEmptyFunctions`|
+|Options|`publicOnly`, `require`, `contexts`, `exemptEmptyFunctions`|
 
 <!-- assertions requireJsdoc -->

.README/rules/require-returns.md

@@ -6,6 +6,10 @@ Requires returns are documented.
 
 - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
     block avoids the need for a `@returns`. Defaults to an empty array.
+- `forceRequireReturn` - Set to `true` to always insist on
+  `@returns` documentation regardless of implicit or explicit `return`'s
+  in the function. May be desired to flag that a project is aware of an
+  `undefined`/`void` return. Defaults to `false`.
 - `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
@@ -17,7 +21,6 @@ Requires returns are documented.
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`returns`|
 |Aliases|`return`|
-|Settings|`forceRequireReturn`|
-|Options|`exemptedBy`, `forceReturnsWithAsync`|
+|Options|`exemptedBy`, `forceRequireReturn`, `forceReturnsWithAsync`|
 
 <!-- assertions requireReturns -->

.README/rules/valid-types.md

@@ -32,12 +32,27 @@ Also impacts behaviors on namepath (or event)-defining and pointing tags:
    allow `#`, `.`, or `~` at the end (which is not allowed at the end of
    normal paths).
 
+#### Options
+
+- `allowEmptyNamepaths` (default: true) - Set to `false` to disallow
+  empty name paths with `@callback`, `@event`, `@class`, `@constructor`,
+  `@constant`, `@const`, `@function`, `@func`, `@method`, `@interface`,
+  `@member`, `@var`, `@mixin`, `@namespace`, `@listens`, `@fires`,
+  or `@emits` (these might often be expected to have an accompanying
+  name path, though they have some indicative value without one; these
+  may also allow names to be defined in another manner elsewhere in
+  the block)
+- `checkSeesForNamepaths` (default: false) - Set this to `true` to insist
+  that `@see` only use name paths (the tag is normally permitted to
+  allow other text)
+
+
 |||
 |---|---|
 |Context|everywhere|
 |Tags|For name only unless otherwise stated: `alias`, `augments`, `borrows`, `callback`, `class` (for name and type), `constant` (for name and type), `enum` (for type), `event`, `external`, `fires`, `function`, `implements` (for type), `interface`, `lends`, `listens`, `member` (for name and type),  `memberof`, `memberof!`, `mixes`, `mixin`, `module` (for name and type), `name`, `namespace` (for name and type), `param` (for name and type), `property` (for name and type), `returns` (for type), `this`, `throws` (for type), `type` (for type), `typedef` (for name and type), `yields` (for type)|
 |Aliases|`extends`, `constructor`, `const`, `host`, `emits`, `func`, `method`, `var`, `arg`, `argument`, `prop`, `return`, `exception`, `yield`|
 |Closure-only|For type only: `package`, `private`, `protected`, `public`, `static`|
-|Settings|`allowEmptyNamepaths`, `checkSeesForNamepaths`|
+|Options|`allowEmptyNamepaths`, `checkSeesForNamepaths`|
 
 <!-- assertions validTypes -->