INCOMPLETE: Expand valid-types tags in docs; flesh out require-jsdoc docs including scopes and tags/aliases

- Docs: Toward resolving gajus#216, document which rules employ each of the settings
- Docs: Add require-jsdoc docs per gajus#208
- Docs: Fix/add to tags listed for rules
- Docs: Observation about `Object.create(null)` and `check-types`

Author: brettz9

.README/README.md

@@ -121,9 +121,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 +183,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 +304,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,6 @@ command.
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
-|Tags|`param`|
+|Tags|`example`|
 
 <!-- assertions checkExamples -->

.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`|
+|Aliases|`constructor`, `const`, `var`, `arg`, `argument`, `prop`, `return`, `exception`|
 
 <!-- assertions checkTypes -->

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

@@ -1,13 +1,16 @@
 ### `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`.
 
 
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
-|Tags|`param`, `returns`|
-
+|Tags|`param`, `returns`, `type`, `typedef`, `throws`, `property`, `constant`, `member`, `module`, `namespace`, `enum`, `implements`, `yields`|
+|Aliases|`arg`, `argument`, `return`, `yield`, `var`, `const`, `exception`
+|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-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,10 @@
+### `require-jsdoc`
+
+Checks for presence of jsdoc comments, across a variety of contexts.
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|N/A|
+
+<!-- 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,6 @@ Requires that all function parameters are documented.
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`param`|
+|Aliases|`arg`, `argument`|
 
 <!-- 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,6 @@ Requires returns are documented.
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`returns`|
+|Aliases|`return`|
 
 <!-- assertions requireReturns -->