- Docs: Toward resolving #216, document which rules employ each of the settings

- Docs: Add require-jsdoc docs per #208
- Docs: Fix/add to tags/aliases listed for rules
- Docs: Add "Settings" column in rule tables to indicate applicable settings
- Docs: Observation about `Object.create(null)` and `check-types`
- Refactoring: Avoid nested `if`

Author: brettz9

.README/README.md

@@ -103,6 +103,17 @@ Finally, enable all of the rules that you would like to use.
 
 ## Settings
 
+### Allow `@private` to disable rules for that comment block
+
+- `settings.jsdoc.allowPrivate` - 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.
@@ -121,9 +132,26 @@ Use `settings.jsdoc.tagNamePreference` to configure a preferred alias name for a
 }
 ```
 
+This setting is utilized by the the rule for tag name checking
+(`check-tag-names`) as well as in the `@param` and `@require` rules:
+
+- `check-param-names`
+- `check-tag-names`
+- `require-hyphen-before-param-description`
+- `require-description`
+- `require-param`
+- `require-param-description`
+- `require-param-name`
+- `require-param-type`
+- `require-returns`
+- `require-returns-check`
+- `require-returns-description`
+- `require-returns-type`
+
 ### Additional Tag Names
 
-Use `settings.jsdoc.additionalTagNames` to configure additional, allowed JSDoc tags. The format of the configuration is as follows:
+Use `settings.jsdoc.additionalTagNames` to configure additional, allowed JSDoc
+tags in the rule `check-tag-names`. The format of the configuration is as follows:
 
 ```json
 {
@@ -166,6 +194,29 @@ The format of the configuration is as follows:
 }
 ```
 
+### Settings to Configure `valid-types`
+
+* `settings.jsdoc.allowEmptyNamepaths` - Set to `false` to disallow
+  empty name paths with `@callback`, `@event`, `@listens`, `@fires`,
+  or `@emits` (these might often be expected to have an accompanying
+  name path, though they have some indicative value without one)
+* `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
@@ -264,6 +315,7 @@ Finally, the following rule pertains to inline disable directives:
 {"gitdown": "include", "file": "./rules/require-description-complete-sentence.md"}
 {"gitdown": "include", "file": "./rules/require-description.md"}
 {"gitdown": "include", "file": "./rules/require-example.md"}
+{"gitdown": "include", "file": "./rules/require-jsdoc.md"}
 {"gitdown": "include", "file": "./rules/require-hyphen-before-param-description.md"}
 {"gitdown": "include", "file": "./rules/require-param-description.md"}
 {"gitdown": "include", "file": "./rules/require-param-name.md"}

.README/rules/check-examples.md

@@ -23,6 +23,7 @@ command.
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
-|Tags|`param`|
+|Tags|`example`|
+|Settings| *See above* |
 
 <!-- assertions checkExamples -->

.README/rules/check-tag-names.md

@@ -79,5 +79,6 @@ yields
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|N/A|
+|Settings|`tagNamePreference`, `additionalTagNames`|
 
 <!-- assertions checkTagNames -->

.README/rules/check-types.md

@@ -30,7 +30,7 @@ new String('lard') // String {0: "l", 1: "a", 2: "r", 3: "d", length: 4}
 new String('lard') === 'lard' // false
 ```
 
-To make things more confusing, there are also object literals and object Objects. But object literals are still static Objects and object Objects are instantiated Objects. So an object primitive is still an object Object.
+To make things more confusing, there are also object literals and object Objects. But object literals are still static Objects and object Objects are instantiated Objects. So an object primitive is still an object Object. (`Object.create(null)` objects are not, however.)
 
 Basically, for primitives, we want to define the type as a primitive, because that's what we use in 99.9% of cases. For everything else, we use the type rather than the primitive. Otherwise it would all just be `{object}`.
 
@@ -47,8 +47,9 @@ Number | **number** | **number** | `(41) instanceof Number` -> **`false`**
 String | **string** | **string** | `("test") instanceof String` -> **`false`**
 
 |||
-|---|---|
+|---|---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
-|Tags|`class`, `constant`, `enum`, `member`, `module`, `namespace`, `param`, `property`, `returns`, `throws`, `type`, `typedef`|
-
+|Tags|`class`, `constant`, `enum`, `implements`, `member`, `module`, `namespace`, `param`, `property`, `returns`, `throws`, `type`, `typedef`, `yields`|
+|Aliases|`constructor`, `const`, `var`, `arg`, `argument`, `prop`, `return`, `exception`|
+|Closure-only|`package`, `private`, `protected`, `public`, `static`|
 <!-- assertions checkTypes -->

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

@@ -1,13 +1,20 @@
 ### `no-undefined-types`
 
-Checks that types in jsdoc comments are defined. This can be used to check unimported types.
+Checks that types in jsdoc comments are defined. This can be used to check
+unimported types.
 
-When enabling this rule, types in jsdoc comments will resolve as used variables, i.e. will not be marked as unused by `no-unused-vars`.
+When enabling this rule, types in jsdoc comments will resolve as used
+variables, i.e. will not be marked as unused by `no-unused-vars`.
 
+The following tags will be checked for name(paths) definitions to also serve
+as a potential "type" for checking the tag types in the table below:
+
+`callback`, `class` (or `constructor`), `constant` (or `const`), `event`, `external` (or `host`), `function` (or `func` or `method`), `interface`, `member` (or `var`), `mixin`, `name`, `namespace`, `typedef`.
 
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
-|Tags|`param`, `returns`|
-
+|Tags|`class`, `constant`, `enum`, `implements`, `member`, `module`, `namespace`, `param`, `property`, `returns`, `throws`, `type`, `typedef`, `yields`|
+|Aliases|`constructor`, `const`, `var`, `arg`, `argument`, `prop`, `return`, `exception`, `yield`|
+|Closure-only|`package`, `private`, `protected`, `public`, `static`|
 <!-- assertions noUndefinedTypes -->

.README/rules/require-description-complete-sentence.md

@@ -11,5 +11,6 @@ Requires that block description and tag description are written in complete sent
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`param`, `returns`|
+|Aliases|`arg`, `argument`, `return`|
 
 <!-- assertions requireDescriptionCompleteSentence -->

.README/rules/require-description.md

@@ -8,6 +8,7 @@ Requires that all functions have a description.
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
-|Tags|`class`, `example`|
+|Tags|`description`|
+|Aliases|`desc`|
 
 <!-- assertions requireDescription -->

.README/rules/require-example.md

@@ -9,5 +9,6 @@ Requires that all functions have examples.
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`example`|
+|Settings|`avoidExampleOnConstructors`|
 
 <!-- assertions requireExample -->

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

@@ -8,5 +8,6 @@ This rule takes one argument. If it is `"always"` then a problem is raised when
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`param`|
+|Aliases|`arg`, `argument`|
 
 <!-- assertions requireHyphenBeforeParamDescription -->

.README/rules/require-jsdoc.md

@@ -0,0 +1,12 @@
+### `require-jsdoc`
+
+Checks for presence of jsdoc comments, on class declarations as well as
+functions.
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `ClassDeclaration`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|N/A|
+|Settings|`exemptEmptyFunctions`|
+
+<!-- assertions requireJsdoc -->

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

@@ -6,5 +6,6 @@ Requires that `@param` tag has `description` value.
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`param`|
+|Aliases|`arg`, `argument`|
 
 <!-- assertions requireParamDescription -->

.README/rules/require-param-name.md

@@ -10,5 +10,6 @@ Requires that all function parameters have name.
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`param`|
+|Aliases|`arg`, `argument`|
 
 <!-- assertions requireParamName -->

.README/rules/require-param-type.md

@@ -6,5 +6,6 @@ Requires that `@param` tag has `type` value.
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`param`|
+|Aliases|`arg`, `argument`|
 
 <!-- assertions requireParamType -->

.README/rules/require-param.md

@@ -6,5 +6,7 @@ Requires that all function parameters are documented.
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`param`|
+|Aliases|`arg`, `argument`|
+|Settings|`allowOverrideWithoutParam`, `allowImplementsWithoutParam`, `allowAugmentsExtendsWithoutParam`|
 
 <!-- assertions requireParam -->

.README/rules/require-returns-check.md

@@ -6,5 +6,6 @@ Checks if the return expression exists in function body and in the comment.
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`returns`|
+|Aliases|`return`|
 
 <!-- assertions requireReturnsCheck -->

.README/rules/require-returns-description.md

@@ -6,5 +6,6 @@ Requires that `@returns` tag has `description` value.
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`returns`|
+|Aliases|`return`|
 
 <!-- assertions requireReturnsDescription -->

.README/rules/require-returns-type.md

@@ -6,5 +6,6 @@ Requires that `@returns` tag has `type` value.
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`returns`|
+|Aliases|`return`|
 
 <!-- assertions requireReturnsType -->

.README/rules/require-returns.md

@@ -6,5 +6,7 @@ Requires returns are documented.
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`returns`|
+|Aliases|`return`|
+|Settings|`forceRequireReturn`|
 
 <!-- assertions requireReturns -->

.README/rules/valid-types.md

@@ -17,6 +17,10 @@ The following apply to the above sets:
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
-|Tags|`param`, `returns`|
+|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`|
 
 <!-- assertions validTypes -->