check-types: Distinguish .<> from <>; support []; check/fix nested array/object types

.README/README.md

@@ -226,12 +226,37 @@ but restricted to `@param`. These settings are now deprecated.
 - `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 keys of this map are the types to be replaced (or forbidden).
+  These keys may include:
+  1. The "ANY" type, `*`
+  1. The pseudo-type `[]` which we use to denote the parent (array)
+    types used in the syntax `string[]`, `number[]`, etc.
+  1. The pseudo-type `.<>` (or `.`) to represent the format `Array.<value>`
+    or `Object.<key, value>`
+  1. The pseudo-type `<>` to represent the format `Array<value>` or
+    `Object<key, value>`
+  1. A plain string type, e.g., `MyType`
+  1. A plain string type followed by one of the above pseudo-types (except
+    for `[]` which is always assumed to be an `Array`), e.g., `Array.`, or
+    `SpecialObject<>`.
+
+  If a bare pseudo-type is used, it will match all parent types of that form.
+  If a pseudo-type prefixed with a type name is used, it will only match
+  parent types of that form and type name.
+
   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)
+    (and which `fix` mode can replace); this can be one of the formats
+    of the keys described above. Note that the format will not be changed
+    unless you use a pseudo-type in the replacement (e.g.,
+    `'Array.<>': 'MyArray'` will change `Array.<string>` to `MyArray.<string>`,
+    preserving the dot; to get rid of the dot, you must use the pseudo-type:
+    `'Array.<>': 'MyArray<>'` which will change `Array.<string>` to
+    `MyArray<string>`). If you use a bare pseudo-type in the replacement,
+    e.g., `'MyArray.<>': '<>'`, the type will be converted to the format
+    of the pseudo-type without changing the type name, i.e., `MyArray.<string>`
+    will become `MyArray<string>` but `Array.<string>` will not be modified.
   - 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
@@ -247,9 +272,9 @@ If `no-undefined-types` has the option key `preferredTypesDefined` set to
 map will be assumed to be defined.
 
 See the option of `check-types`, `unifyParentAndChildTypeChecks`, for
-how the keys of `preferredTypes` may have `<>` appended and its bearing
-on whether types are checked as parents/children only (e.g., to match `Array`
-if the type is `Array` vs. `Array.<string>`).
+how the keys of `preferredTypes` may have `<>` or `.<>` (or just `.`)
+appended and its bearing on whether types are checked as parents/children
+only (e.g., to match `Array` if the type is `Array` vs. `Array.<string>`).
 
 ### Settings to Configure `valid-types`
 

.README/rules/check-types.md

@@ -25,17 +25,25 @@ RegExp
   - 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.
-  - with the key `unifyParentAndChildTypeChecks` to treat
-    `settings.jsdoc.preferredTypes` keys the same whether they are of the form
-    `SomeType` or `SomeType<>`. If this is `false` or unset, the former
-    will only apply to types which are not parent types/unions whereas the
-    latter will only apply for parent types/unions.
+  - 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
+    `SomeType<aChildType>`, `SomeType.<aChildType>`, or if `SomeType` is
+    `Array` (or `[]`), it will match `aChildType[]`. If this is `false` or
+    unset, the former format will only apply to types which are not parent
+    types/unions whereas the latter formats will only apply for parent
+    types/unions. The special types `[]`, `.<>` (or `.`), and `<>`
+    act only as parent types (and will not match a bare child type such as
+    `Array` even when unified, though, as mentioned, `Array` will match
+    say `string[]` or `Array.<string>` when unified). The special type
+    `*` is only a child type. Note that there is no detection of parent
+    and child type together, e.g., you cannot specify preferences for
+    `string[]` specifically as distinct from say `number[]`, but you can
+    target both with `[]` or the child types `number` or `string`.
 
 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()`.