INCOMPLETE: expand valid-types tags; check if no-undefined-types and check-types should be checking borrows and namepath types; flesh out require-jsdoc including scopes and tags/aliases

- Fix: Remove `parameter` as accepted synonym for `@param` (not listed at site)
- Enhancement: Have `require-hyphen-before-param-description` check `tagNamePreference` setting
- Refactoring: Avoid checking for preferred name for `example` (as there are no official synonyms)
- Refactoring: Toward resolving gajus#216, group settings by which rules use them
- Refactoring: Rename `isLink` inner function to `isInlineTag` for accuracy
- 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,16 @@ 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 `check-examples`
 
 The settings below all impact the `check-examples` rule and default to
@@ -264,6 +291,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 -->

src/iterateJsdoc.js

@@ -193,22 +193,32 @@ export default (iterator, options) => {
      */
     create (context) {
       const sourceCode = context.getSourceCode();
+
+      // `check-tag-names` and many require/param rules
       const tagNamePreference = _.get(context, 'settings.jsdoc.tagNamePreference') || {};
+
+      // `check-tag-names` only
+      const additionalTagNames = _.get(context, 'settings.jsdoc.additionalTagNames') || {};
+
+      // `check-examples` only
       const exampleCodeRegex = _.get(context, 'settings.jsdoc.exampleCodeRegex') || null;
       const rejectExampleCodeRegex = _.get(context, 'settings.jsdoc.rejectExampleCodeRegex') || null;
       const matchingFileName = _.get(context, 'settings.jsdoc.matchingFileName') || null;
-      const additionalTagNames = _.get(context, 'settings.jsdoc.additionalTagNames') || {};
       const baseConfig = _.get(context, 'settings.jsdoc.baseConfig') || {};
       const configFile = _.get(context, 'settings.jsdoc.configFile');
       const eslintrcForExamples = _.get(context, 'settings.jsdoc.eslintrcForExamples') !== false;
       const allowInlineConfig = _.get(context, 'settings.jsdoc.allowInlineConfig') !== false;
-      const allowEmptyNamepaths = _.get(context, 'settings.jsdoc.allowEmptyNamepaths') !== false;
       const reportUnusedDisableDirectives = _.get(context, 'settings.jsdoc.reportUnusedDisableDirectives') !== false;
       const captionRequired = Boolean(_.get(context, 'settings.jsdoc.captionRequired'));
       const noDefaultExampleRules = Boolean(_.get(context, 'settings.jsdoc.noDefaultExampleRules'));
+
+      // `require-param` only
       const allowOverrideWithoutParam = Boolean(_.get(context, 'settings.jsdoc.allowOverrideWithoutParam'));
       const allowImplementsWithoutParam = Boolean(_.get(context, 'settings.jsdoc.allowImplementsWithoutParam'));
       const allowAugmentsExtendsWithoutParam = Boolean(_.get(context, 'settings.jsdoc.allowAugmentsExtendsWithoutParam'));
+
+      // `valid-types` only
+      const allowEmptyNamepaths = _.get(context, 'settings.jsdoc.allowEmptyNamepaths') !== false;
       const checkSeesForNamepaths = Boolean(_.get(context, 'settings.jsdoc.checkSeesForNamepaths'));
 
       const checkJsdoc = (node) => {

src/rules/requireExample.js

@@ -3,10 +3,9 @@ import iterateJsdoc from '../iterateJsdoc';
 
 export default iterateJsdoc(({
   jsdoc,
-  report,
-  utils
+  report
 }) => {
-  const targetTagName = utils.getPreferredTagName('example');
+  const targetTagName = 'example';
 
   const functionExamples = _.filter(jsdoc.tags, {
     tag: targetTagName

src/rules/requireHyphenBeforeParamDescription.js

@@ -6,12 +6,14 @@ export default iterateJsdoc(({
   jsdoc,
   report,
   context,
-  jsdocNode
+  jsdocNode,
+  utils
 }) => {
   let always;
 
+  const targetTagName = utils.getPreferredTagName('param');
   const jsdocTags = _.filter(jsdoc.tags, {
-    tag: 'param'
+    tag: targetTagName
   });
 
   if (_.has(context.options, 0)) {
@@ -27,14 +29,14 @@ export default iterateJsdoc(({
 
     if (always) {
       if (!_.startsWith(jsdocTag.description, '-')) {
-        report('There must be a hyphen before @param description.', (fixer) => {
+        report('There must be a hyphen before @' + targetTagName + ' description.', (fixer) => {
           const replacement = sourceCode.getText(jsdocNode).replace(jsdocTag.description, '- ' + jsdocTag.description);
 
           return fixer.replaceText(jsdocNode, replacement);
         }, jsdocTag);
       }
     } else if (_.startsWith(jsdocTag.description, '-')) {
-      report('There must be no hyphen before @param description.', (fixer) => {
+      report('There must be no hyphen before @' + targetTagName + ' description.', (fixer) => {
         const [unwantedPart] = /-\s*/.exec(jsdocTag.description);
 
         const replacement = sourceCode

src/rules/validTypes.js

@@ -3,7 +3,7 @@ import {parse} from 'jsdoctypeparser';
 import iterateJsdoc from '../iterateJsdoc';
 
 /** @param {string} tag */
-const isLink = (tag) => {
+const isInlineTag = (tag) => {
   return /^(@link|@linkcode|@linkplain|@tutorial) /.test(tag);
 };
 
@@ -48,7 +48,7 @@ export default iterateJsdoc(({
         return;
       }
       validTypeParsing(tag.name);
-    } else if (tag.type && !isLink(tag.type)) {
+    } else if (tag.type && !isInlineTag(tag.type)) {
       validTypeParsing(tag.type);
     }
   });

src/tagNames.js

@@ -72,8 +72,7 @@ export default {
   package: [],
   param: [
     'arg',
-    'argument',
-    'parameter'
+    'argument'
   ],
   private: [],
   property: [