Merge branch 'master' into add-more-type-checks-to-valid-types

* master:
  feat(require-description-complete-sentence): validate explicit `description` tags
  fix(check-types): remove template substitution variables, `badType`, `preferredType`, and `replacement` (gajus#310)
  feat: remove `preferredTypesDefined` option in favor of making it apply automatically
  feat(check-tag-names): auto-allow tags in `tagNamePreference` setting to be defined; add `definedTags` option to replace `additionalTagNames.customTags` setting
  feat(check-tag-names): allow rejecting normally valid tag names and/or providing custom error messages when suggesting tags to reject or replace (fixes gajus#108)
  Allow rejecting normally valid tag names and/or providing custom error messages when suggesting tags to reject or replace (gajus#302)
  docs: indicate option defaults (fixes part of gajus#256) and ensure optioins all listed in docs
  chore: update Babel devDeps.
  feat(no-undefined-types): handle GCC generic functions
  docs: generate docs
  Add an invalid test case for incorrect @template type
  fix: reverse jsdoctypeparser update until traversal issue with "external:..." can be fixed
  feat: bump jsdoctypeparser to 5.0.0
  docs: generate docs
  Add support for generic functions in addition to classes

Author: brettz9

.README/README.md

@@ -147,6 +147,61 @@ Use `settings.jsdoc.tagNamePreference` to configure a preferred alias name for a
 }
 ```
 
+One may also use an object with a `message` and `replacement`.
+
+The following will report the message `@extends is to be used over @augments as it is more evocative of classes than @augments` upon encountering `@augments`.
+
+```json
+{
+    "rules": {},
+    "settings": {
+        "jsdoc": {
+            "tagNamePreference": {
+                "augments": {
+                  "message": "@extends is to be used over @augments as it is more evocative of classes than @augments",
+                  "replacement": "extends"
+                }
+            }
+        }
+    }
+}
+```
+
+If one wishes to reject a normally valid tag, e.g., `@todo`, one may set the tag to `false`:
+
+```json
+{
+    "rules": {},
+    "settings": {
+        "jsdoc": {
+            "tagNamePreference": {
+                "todo": false
+            }
+        }
+    }
+}
+```
+
+Or one may set the targeted tag to an object with a custom `message`, but without a `replacement` property:
+
+```json
+{
+    "rules": {},
+    "settings": {
+        "jsdoc": {
+            "tagNamePreference": {
+                "todo": {
+                  "message": "We expect immediate perfection, so don't leave to-dos in your code."
+                }
+            }
+        }
+    }
+}
+```
+
+Note that the preferred tags indicated in the `settings.jsdoc.tagNamePreference`
+map will be assumed to be defined by `check-tag-names`.
+
 The defaults in `eslint-plugin-jsdoc` (for tags which offer
 aliases) are as follows:
 
@@ -183,24 +238,6 @@ This setting is utilized by the the rule for tag name checking
 - `require-returns-description`
 - `require-returns-type`
 
-### Additional Tag Names
-
-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
-{
-    "rules": {},
-    "settings": {
-        "jsdoc": {
-            "additionalTagNames": {
-                "customTags": ["define", "record"]
-            }
-        }
-    }
-}
-```
-
 ### `@override`/`@augments`/`@extends`/`@implements` Without Accompanying `@param`/`@description`/`@example`/`@returns`
 
 The following settings allows the element(s) they reference to be omitted
@@ -272,15 +309,12 @@ but restricted to `@param`. These settings are now deprecated.
     when encountering the discouraged type and, if a type is to be preferred
     in its place, the key `replacement` to indicate the type that should be
     used in its place (and which `fix` mode can replace) or `false` if
-    forbidding the type. The message string will have the following
-    substrings with special meaning replaced with their corresponding
-    value (`{{tagName}}`, `{{tagValue}}`, `{{badType}}`, and
-    `{{preferredType}}` (or `{{replacement}}`), noting that the latter is
-    of no use when one is merely forbidding a type).
-
-If `no-undefined-types` has the option key `preferredTypesDefined` set to
-`true`, the preferred types indicated in the `settings.jsdoc.preferredTypes`
-map will be assumed to be defined.
+    forbidding the type. The message string will have the substrings with
+    special meaning, `{{tagName}}` and `{{tagValue}}`, replaced with their
+    corresponding value.
+
+Note that the preferred types indicated as targets in `settings.jsdoc.preferredTypes`
+map will be assumed to be defined by `no-undefined-types`.
 
 See the option of `check-types`, `unifyParentAndChildTypeChecks`, for
 how the keys of `preferredTypes` may have `<>` or `.<>` (or just `.`)

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

@@ -75,10 +75,26 @@ version
 yields
 ```
 
+Note that the tags indicated as replacements in `settings.jsdoc.tagNamePreference` will automatically be considered as valid.
+
+#### Options
+
+##### `definedTags`
+
+Use an array of `definedTags` strings to configure additional, allowed JSDoc tags.
+The format is as follows:
+
+```json
+{
+  "definedTags": ["define", "record"]
+}
+```
+
 |||
 |---|---|
 |Context|everywhere|
 |Tags|N/A|
-|Settings|`tagNamePreference`, `additionalTagNames`|
+|Options|`definedTags`|
+|Settings|`tagNamePreference`|
 
 <!-- assertions checkTagNames -->

.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

@@ -20,23 +20,24 @@ The following types are always considered defined.
 - `any`, `*`
 - `Array`, `Object`, `RegExp`, `Date`, `Function`
 
+Note that preferred types indicated within `settings.jsdoc.preferredTypes` will
+also be assumed to be defined.
+
 #### Options
 
-An option object may have the following keys:
+An option object may have the following key:
 
-- `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.
 - `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.
 
 |||
 |---|---|
 |Context|everywhere|
 |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`|
-|Options|`preferredTypesDefined`, `definedTypes`|
+|Options|`definedTypes`|
 |Settings|`preferredTypes`|
 
 <!-- assertions noUndefinedTypes -->

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

@@ -1,16 +1,18 @@
 ### `require-description-complete-sentence`
 
-Requires that block description and tag description are written in complete sentences, i.e.,
+Requires that block description, explicit `@description`, and `@param`/`@returns`
+tag descriptions are written in complete sentences, i.e.,
 
 * Description must start with an uppercase alphabetical character.
 * Paragraphs must start with an uppercase alphabetical character.
 * Sentences must end with a period.
-* Every line in a paragraph (except the first) which starts with an uppercase character must be preceded by a line ending with a period.
+* Every line in a paragraph (except the first) which starts with an uppercase
+  character must be preceded by a line ending with a period.
 
 |||
 |---|---|
 |Context|everywhere|
-|Tags|`param`, `returns`|
-|Aliases|`arg`, `argument`, `return`|
+|Tags|`param`, `returns`, `description`|
+|Aliases|`arg`, `argument`, `return`, `desc`|
 
 <!-- assertions requireDescriptionCompleteSentence -->

.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}]