Merge pull request #247 from brettz9/check-types-prefer-types

`preferredTypes`

Author: brettz9

.README/README.md

@@ -198,6 +198,31 @@ The format of the configuration is as follows:
 }
 ```
 
+### Settings to Configure `check-types` and `no-undefined-types`
+
+- `settings.jsdoc.preferredTypes` An option map to indicate preferred
+  or forbidden types (if default types are indicated here, these will
+  have precedence over the default recommendations for `check-types`).
+  The keys of this map are the types to be replaced (or forbidden) and
+  can include the "ANY" type, `*`.
+  The values can be:
+  - `false` to forbid the type
+  - a string to indicate the type that should be preferred in its place
+    (and which `fix` mode can replace)
+  - an object with the key `message` to provide a specific error message
+    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}}`, 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.
+
 ### Settings to Configure `valid-types`
 
 * `settings.jsdoc.allowEmptyNamepaths` - Set to `false` to disallow

.README/rules/check-types.md

@@ -2,7 +2,7 @@
 
 Reports invalid types.
 
-Ensures that case of native types is the same as in this list:
+By default, ensures that case of native types is the same as in this list:
 
 ```
 undefined
@@ -16,6 +16,17 @@ Date
 RegExp
 ```
 
+#### Options
+
+`check-types` allows one option:
+
+- 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.
+
+See also the documentation on `settings.jsdoc.preferredTypes` which impacts
+the behavior of `check-types`.
+
 #### Why not capital case everything?
 
 Why are `boolean`, `number` and `string` exempt from starting with a capital letter? Let's take `string` as an example. In Javascript, everything is an object. The string Object has prototypes for string functions such as `.toUpperCase()`.

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

@@ -6,11 +6,30 @@ 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`.
 
-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:
+In addition to considering globals found in code (or in ESLint-indicated
+`globals`) as defined, the following tags will also be checked for
+name(path) 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`.
 
+The following types are always considered defined.
+
+- `null`, `undefined`, `string`, `boolean`
+- `number`, `NaN`, `Infinity`
+- `any`, `*`
+- `Array`, `Object`, `RegExp`, `Date`, `Function`
+
+#### Options
+
+An option object may have the following keys:
+
+- `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.)
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|