feat(escape-inline-tags): add new rule

.README/README.md

@@ -227,6 +227,7 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/check-values": 1, // Recommended
         "jsdoc/convert-to-jsdoc-comments": 1,
         "jsdoc/empty-tags": 1, // Recommended
+        "jsdoc/escape-inline-tags": 1, // Recommended for TS configs
         "jsdoc/implements-on-classes": 1, // Recommended
         "jsdoc/imports-as-dependencies": 1,
         "jsdoc/informative-docs": 1,

.README/rules/escape-inline-tags.md

@@ -0,0 +1,34 @@
+# `escape-inline-tags`
+
+Reports use of JSDoc tags in non-tag positions (in the default "typescript" mode).
+
+Note that while the JSDoc standard refers to inline tags as those being surrounded
+by curly brackets, such as those in the form `{@link https://example.com}`, for the
+purposes of this rule, we are referring to inline tags as a simple reference to
+tags such as `@param` outside of the normal location of a tag and which may need to
+be wrapped in `{}` to be proper inline JSDoc or need to be escaped with `\` or
+wrapped with ` to be normal text. E.g.
+
+```js
+/** Supports shorthands such as `@yearly` to simplify setup. */
+```
+
+## Options
+
+{"gitdown": "options"}
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|``|
+|Recommended|true (unless `mode` is changed away from "typescript")|
+|Settings|`mode`|
+|Options|`allowedInlineTags`, `enableFixer`, `fixType`|
+
+## Failing examples
+
+<!-- assertions-failing escapeInlineTags -->
+
+## Passing examples
+
+<!-- assertions-passing escapeInlineTags -->

README.md

@@ -254,6 +254,7 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/check-values": 1, // Recommended
         "jsdoc/convert-to-jsdoc-comments": 1,
         "jsdoc/empty-tags": 1, // Recommended
+        "jsdoc/escape-inline-tags": 1, // Recommended for TS configs
         "jsdoc/implements-on-classes": 1, // Recommended
         "jsdoc/imports-as-dependencies": 1,
         "jsdoc/informative-docs": 1,
@@ -442,6 +443,7 @@ non-default-recommended fixer).
 |:heavy_check_mark:|| [check-values](./docs/rules/check-values.md#readme) | This rule checks the values for a handful of tags: `@version`, `@since`, `@license` and `@author`. |
 ||:wrench:| [convert-to-jsdoc-comments](./docs/rules/convert-to-jsdoc-comments.md#readme) | Converts non-JSDoc comments preceding or following nodes into JSDoc ones |
 |:heavy_check_mark:|:wrench:| [empty-tags](./docs/rules/empty-tags.md#readme) | Checks tags that are expected to be empty (e.g., `@abstract` or `@async`), reporting if they have content |
+|:heavy_check_mark:|:wrench:| [escape-inline-tags](./docs/rules/escape-inline-tags.md#readme) | Reports use of JSDoc tags in non-tag positions (in the default "typescript" mode). |
 |:heavy_check_mark:|| [implements-on-classes](./docs/rules/implements-on-classes.md#readme) | Prohibits use of `@implements` on non-constructor functions (to enforce the tag only being used on classes/constructors). |
 ||| [imports-as-dependencies](./docs/rules/imports-as-dependencies.md#readme) | Reports if JSDoc `import()` statements point to a package which is not listed in `dependencies` or `devDependencies` |
 ||| [informative-docs](./docs/rules/informative-docs.md#readme) | This rule reports doc comments that only restate their attached name. |

docs/rules/check-line-alignment.md

@@ -56,43 +56,51 @@ If a spacing is not defined, it defaults to one.
 #### <code>postDelimiter</code>
 
 Affects spacing after the asterisk (e.g., `*   @param`)
+
 <a name="user-content-check-line-alignment-options-customspacings-posthyphen"></a>
 <a name="check-line-alignment-options-customspacings-posthyphen"></a>
 #### <code>postHyphen</code>
 
 Affects spacing after any hyphens in the description (e.g., `* @param {someType} name -  A description`)
+
 <a name="user-content-check-line-alignment-options-customspacings-postname"></a>
 <a name="check-line-alignment-options-customspacings-postname"></a>
 #### <code>postName</code>
 
 Affects spacing after the name (e.g., `* @param {someType} name   `)
+
 <a name="user-content-check-line-alignment-options-customspacings-posttag"></a>
 <a name="check-line-alignment-options-customspacings-posttag"></a>
 #### <code>postTag</code>
 
 Affects spacing after the tag (e.g., `* @param  `)
+
 <a name="user-content-check-line-alignment-options-customspacings-posttype"></a>
 <a name="check-line-alignment-options-customspacings-posttype"></a>
 #### <code>postType</code>
 
 Affects spacing after the type (e.g., `* @param {someType}   `)
+
 <a name="user-content-check-line-alignment-options-disablewrapindent"></a>
 <a name="check-line-alignment-options-disablewrapindent"></a>
 ### <code>disableWrapIndent</code>
 
 Disables `wrapIndent`; existing wrap indentation is preserved without changes.
+
 <a name="user-content-check-line-alignment-options-preservemaindescriptionpostdelimiter"></a>
 <a name="check-line-alignment-options-preservemaindescriptionpostdelimiter"></a>
 ### <code>preserveMainDescriptionPostDelimiter</code>
 
 A boolean to determine whether to preserve the post-delimiter spacing of the
 main description. If `false` or unset, will be set to a single space.
+
 <a name="user-content-check-line-alignment-options-tags"></a>
 <a name="check-line-alignment-options-tags"></a>
 ### <code>tags</code>
 
 Use this to change the tags which are sought for alignment changes. Defaults to an array of
 `['param', 'arg', 'argument', 'property', 'prop', 'returns', 'return', 'template']`.
+
 <a name="user-content-check-line-alignment-options-wrapindent"></a>
 <a name="check-line-alignment-options-wrapindent"></a>
 ### <code>wrapIndent</code>

docs/rules/check-param-names.md

@@ -72,18 +72,21 @@ If set to `true`, this option will allow extra `@param` definitions (e.g.,
 representing future expected or virtual params) to be present without needing
 their presence within the function signature. Other inconsistencies between
 `@param`'s and present function parameters will still be reported.
+
 <a name="user-content-check-param-names-options-checkdestructured"></a>
 <a name="check-param-names-options-checkdestructured"></a>
 ### <code>checkDestructured</code>
 
 Whether to check destructured properties. Defaults to `true`.
+
 <a name="user-content-check-param-names-options-checkrestproperty"></a>
 <a name="check-param-names-options-checkrestproperty"></a>
 ### <code>checkRestProperty</code>
 
 If set to `true`, will require that rest properties are documented and
 that any extraneous properties (which may have been within the rest property)
 are documented. Defaults to `false`.
+
 <a name="user-content-check-param-names-options-checktypespattern"></a>
 <a name="check-param-names-options-checktypespattern"></a>
 ### <code>checkTypesPattern</code>
@@ -123,6 +126,7 @@ your expression as a string, but like a literal, e.g., `/^object$/vi`.
 You could set this regular expression to a more expansive list, or you
 could restrict it such that even types matching those strings would not
 need destructuring.
+
 <a name="user-content-check-param-names-options-disableextrapropertyreporting"></a>
 <a name="check-param-names-options-disableextrapropertyreporting"></a>
 ### <code>disableExtraPropertyReporting</code>
@@ -134,11 +138,13 @@ their own types. Note that extra properties will always be reported if another
 item at the same level is destructured as destructuring will prevent other
 access and this option is only intended to permit documenting extra properties
 that are available and actually used in the function.
+
 <a name="user-content-check-param-names-options-disablemissingparamchecks"></a>
 <a name="check-param-names-options-disablemissingparamchecks"></a>
 ### <code>disableMissingParamChecks</code>
 
 Whether to avoid checks for missing `@param` definitions. Defaults to `false`. Change to `true` if you want to be able to omit properties.
+
 <a name="user-content-check-param-names-options-enablefixer"></a>
 <a name="check-param-names-options-enablefixer"></a>
 ### <code>enableFixer</code>
@@ -149,6 +155,7 @@ names).
 Note that this option will remove duplicates of the same name even if
 the definitions do not match in other ways (e.g., the second param will
 be removed even if it has a different type or description).
+
 <a name="user-content-check-param-names-options-usedefaultobjectproperties"></a>
 <a name="check-param-names-options-usedefaultobjectproperties"></a>
 ### <code>useDefaultObjectProperties</code>

docs/rules/check-tag-names.md

@@ -238,18 +238,21 @@ The format is as follows:
   "definedTags": ["note", "record"]
 }
 ```
+
 <a name="user-content-check-tag-names-options-enablefixer"></a>
 <a name="check-tag-names-options-enablefixer"></a>
 ### <code>enableFixer</code>
 
 Set to `false` to disable auto-removal of types that are redundant with the [`typed` option](#user-content-typed).
+
 <a name="user-content-check-tag-names-options-inlinetags"></a>
 <a name="check-tag-names-options-inlinetags"></a>
 ### <code>inlineTags</code>
 
 List of tags to allow inline.
 
 Defaults to array of `'link', 'linkcode', 'linkplain', 'tutorial'`
+
 <a name="user-content-check-tag-names-options-jsxtags"></a>
 <a name="check-tag-names-options-jsxtags"></a>
 ### <code>jsxTags</code>
@@ -264,6 +267,7 @@ jsxRuntime
 ```
 
 For more information, see the [babel documentation](https://babeljs.io/docs/en/babel-plugin-transform-react-jsx).
+
 <a name="user-content-check-tag-names-options-typed"></a>
 <a name="check-tag-names-options-typed"></a>
 ### <code>typed</code>

docs/rules/check-types.md

@@ -45,13 +45,15 @@ A single options object has the following properties.
 ### <code>exemptTagContexts</code>
 
 Avoids reporting when a bad type is found on a specified tag.
+
 A single options object has the following properties.
 
 <a name="user-content-check-types-options-exempttagcontexts-tag"></a>
 <a name="check-types-options-exempttagcontexts-tag"></a>
 ##### <code>tag</code>
 
 Set a key `tag` to the tag to exempt
+
 <a name="user-content-check-types-options-exempttagcontexts-types"></a>
 <a name="check-types-options-exempttagcontexts-types"></a>
 ##### <code>types</code>
@@ -65,13 +67,15 @@ behavior of `settings.jsdoc.preferredTypes`. This option is useful
 for normally restricting generic types like `object` with
 `preferredTypes`, but allowing `typedef` to indicate that its base
 type is `object`.
+
 <a name="user-content-check-types-options-nodefaults"></a>
 <a name="check-types-options-nodefaults"></a>
 ### <code>noDefaults</code>
 
 Insists 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. The option's default is `false`.
+
 <a name="user-content-check-types-options-unifyparentandchildtypechecks"></a>
 <a name="check-types-options-unifyparentandchildtypechecks"></a>
 ### <code>unifyParentAndChildTypeChecks</code>

docs/rules/check-values.md

@@ -42,12 +42,14 @@ A single options object has the following properties.
 
 An array of allowable author values. If absent, only non-whitespace will
 be checked for.
+
 <a name="user-content-check-values-options-allowedlicenses"></a>
 <a name="check-values-options-allowedlicenses"></a>
 ### <code>allowedLicenses</code>
 
 An array of allowable license values or `true` to allow any license text.
 If present as an array, will be used in place of [SPDX identifiers](https://spdx.org/licenses/).
+
 <a name="user-content-check-values-options-licensepattern"></a>
 <a name="check-values-options-licensepattern"></a>
 ### <code>licensePattern</code>
@@ -62,6 +64,7 @@ Note that the `/` delimiters are optional, but necessary to add flags.
 
 Defaults to using the `v` flag, so to add your own flags, encapsulate
 your expression as a string, but like a literal, e.g., `/^mit$/vi`.
+
 <a name="user-content-check-values-options-numericonlyvariation"></a>
 <a name="check-values-options-numericonlyvariation"></a>
 ### <code>numericOnlyVariation</code>

docs/rules/convert-to-jsdoc-comments.md

@@ -28,6 +28,7 @@ An array of prefixes to allow at the beginning of a comment.
 Defaults to `['@ts-', 'istanbul ', 'c8 ', 'v8 ', 'eslint', 'prettier-']`.
 
 Supplying your own value overrides the defaults.
+
 <a name="user-content-convert-to-jsdoc-comments-options-contexts"></a>
 <a name="convert-to-jsdoc-comments-options-contexts"></a>
 ### <code>contexts</code>
@@ -48,6 +49,7 @@ The contexts array which will be checked for content on the same line after.
 Can either be strings or an object with a `context` string and an optional, default `false` `inlineCommentBlock` boolean.
 
 Defaults to an empty array.
+
 <a name="user-content-convert-to-jsdoc-comments-options-contextsbeforeandafter"></a>
 <a name="convert-to-jsdoc-comments-options-contextsbeforeandafter"></a>
 ### <code>contextsBeforeAndAfter</code>
@@ -58,11 +60,13 @@ line after.
 Can either be strings or an object with a `context` string and an optional, default `false` `inlineCommentBlock` boolean.
 
 Defaults to `VariableDeclarator`, `TSPropertySignature`, `PropertyDefinition`.
+
 <a name="user-content-convert-to-jsdoc-comments-options-enablefixer"></a>
 <a name="convert-to-jsdoc-comments-options-enablefixer"></a>
 ### <code>enableFixer</code>
 
 Set to `false` to disable fixing.
+
 <a name="user-content-convert-to-jsdoc-comments-options-enforcejsdoclinestyle"></a>
 <a name="convert-to-jsdoc-comments-options-enforcejsdoclinestyle"></a>
 ### <code>enforceJsdocLineStyle</code>

docs/rules/empty-tags.md

@@ -61,7 +61,6 @@ add them within this option.
 ```
 
 
-
 <a name="user-content-context-and-settings"></a>
 <a name="context-and-settings"></a>
 ## Context and settings