Skip to content

Check tag names breaking #303

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Check tag names breaking #303

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 2 additions & 18 deletions .README/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,8 @@ Or one may set the targeted tag to an object with a custom `message`, but withou
}
```

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:
Expand Down Expand Up @@ -236,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
Expand Down
18 changes: 17 additions & 1 deletion .README/rules/check-tag-names.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 -->
95 changes: 56 additions & 39 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@ JSDoc linting rules for ESLint.
* [Allow `@private` to disable rules for that comment block](#eslint-plugin-jsdoc-settings-allow-private-to-disable-rules-for-that-comment-block)
* [Exempting empty functions from `require-jsdoc`](#eslint-plugin-jsdoc-settings-exempting-empty-functions-from-require-jsdoc)
* [Alias Preference](#eslint-plugin-jsdoc-settings-alias-preference)
* [Additional Tag Names](#eslint-plugin-jsdoc-settings-additional-tag-names)
* [`@override`/`@augments`/`@extends`/`@implements` Without Accompanying `@param`/`@description`/`@example`/`@returns`](#eslint-plugin-jsdoc-settings-override-augments-extends-implements-without-accompanying-param-description-example-returns)
* [Settings to Configure `check-types` and `no-undefined-types`](#eslint-plugin-jsdoc-settings-settings-to-configure-check-types-and-no-undefined-types)
* [Settings to Configure `valid-types`](#eslint-plugin-jsdoc-settings-settings-to-configure-valid-types)
Expand Down Expand Up @@ -249,6 +248,8 @@ Or one may set the targeted tag to an object with a custom `message`, but withou
}
```

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:
Expand Down Expand Up @@ -286,25 +287,6 @@ This setting is utilized by the the rule for tag name checking
- `require-returns-description`
- `require-returns-type`

<a name="eslint-plugin-jsdoc-settings-additional-tag-names"></a>
### 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"]
}
}
}
}
```

<a name="eslint-plugin-jsdoc-settings-override-augments-extends-implements-without-accompanying-param-description-example-returns"></a>
### <code>@override</code>/<code>@augments</code>/<code>@extends</code>/<code>@implements</code> Without Accompanying <code>@param</code>/<code>@description</code>/<code>@example</code>/<code>@returns</code>

Expand Down Expand Up @@ -1249,11 +1231,29 @@ version
yields
```

Note that the tags indicated as replacements in `settings.jsdoc.tagNamePreference` will automatically be considered as valid.

<a name="eslint-plugin-jsdoc-rules-check-tag-names-options"></a>
#### Options

<a name="eslint-plugin-jsdoc-rules-check-tag-names-options-definedtags"></a>
##### <code>definedTags</code>

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`|

The following patterns are considered problems:

Expand Down Expand Up @@ -1327,7 +1327,7 @@ function quux (foo) {
function quux (foo) {

}
// Settings: {"jsdoc":{"additionalTagNames":{"customTags":["bar"]}}}
// Options: [{"definedTags":["bar"]}]
// Message: Invalid JSDoc tag name "baz".

/**
Expand All @@ -1337,7 +1337,7 @@ function quux (foo) {
function quux (foo) {

}
// Settings: {"jsdoc":{"additionalTagNames":{"customTags":["bar"]}}}
// Options: [{"definedTags":["bar"]}]
// Message: Invalid JSDoc tag name "baz".

/**
Expand Down Expand Up @@ -1375,6 +1375,15 @@ function quux () {
}
// Settings: {"jsdoc":{"tagNamePreference":{"todo":{"message":"Please use x-todo instead of todo","replacement":"x-todo"}}}}
// Message: Please use x-todo instead of todo

/**
* @todo
*/
function quux () {

}
// Settings: {"jsdoc":{"tagNamePreference":{"todo":55}}}
// Message: Invalid `settings.jsdoc.tagNamePreference`. Values must be falsy, a string, or an object.
````

The following patterns are not considered problems:
Expand Down Expand Up @@ -1408,15 +1417,23 @@ function quux (foo) {
function quux (foo) {

}
// Settings: {"jsdoc":{"additionalTagNames":{"customTags":["bar"]}}}
// Options: [{"definedTags":["bar"]}]

/**
* @baz @bar foo
*/
function quux (foo) {

}
// Options: [{"definedTags":["baz","bar"]}]

/**
* @baz @bar foo
*/
function quux (foo) {

}
// Settings: {"jsdoc":{"additionalTagNames":{"customTags":["baz","bar"]}}}
// Settings: {"jsdoc":{"tagNamePreference":{"param":"baz","returns":{"message":"Prefer `bar`","replacement":"bar"},"todo":false}}}

/**
* @abstract
Expand Down Expand Up @@ -1521,7 +1538,7 @@ Date
RegExp
```

<a name="eslint-plugin-jsdoc-rules-check-types-options"></a>
<a name="eslint-plugin-jsdoc-rules-check-types-options-1"></a>
#### Options

`check-types` allows one option:
Expand Down Expand Up @@ -2402,10 +2419,10 @@ by our supported Node versions):

``^([A-Z]|[`\\d_])[\\s\\S]*[.?!`]$``

<a name="eslint-plugin-jsdoc-rules-match-description-options-1"></a>
<a name="eslint-plugin-jsdoc-rules-match-description-options-2"></a>
#### Options

<a name="eslint-plugin-jsdoc-rules-match-description-options-1-matchdescription"></a>
<a name="eslint-plugin-jsdoc-rules-match-description-options-2-matchdescription"></a>
##### <code>matchDescription</code>

You can supply your own expression to override the default, passing a
Expand All @@ -2420,7 +2437,7 @@ You can supply your own expression to override the default, passing a
As with the default, the supplied regular expression will be applied with the
Unicode (`"u"`) flag and is *not* case-insensitive.

<a name="eslint-plugin-jsdoc-rules-match-description-options-1-tags"></a>
<a name="eslint-plugin-jsdoc-rules-match-description-options-2-tags"></a>
##### <code>tags</code>

If you want different regular expressions to apply to tags, you may use
Expand All @@ -2447,7 +2464,7 @@ tag should be linted with the `matchDescription` value (or the default).
}
```

<a name="eslint-plugin-jsdoc-rules-match-description-options-1-maindescription"></a>
<a name="eslint-plugin-jsdoc-rules-match-description-options-2-maindescription"></a>
##### <code>mainDescription</code>

If you wish to override the main function description without changing the
Expand All @@ -2469,7 +2486,7 @@ There is no need to add `mainDescription: true`, as by default, the main
function (and only the main function) is linted, though you may disable checking
it by setting it to `false`.

<a name="eslint-plugin-jsdoc-rules-match-description-options-1-contexts"></a>
<a name="eslint-plugin-jsdoc-rules-match-description-options-2-contexts"></a>
##### <code>contexts</code>

Set this to an array of strings representing the AST context
Expand Down Expand Up @@ -2915,7 +2932,7 @@ const q = {

Enforces a consistent padding of the block description.

<a name="eslint-plugin-jsdoc-rules-newline-after-description-options-2"></a>
<a name="eslint-plugin-jsdoc-rules-newline-after-description-options-3"></a>
#### 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"`.
Expand Down Expand Up @@ -3075,7 +3092,7 @@ The following types are always considered defined.
- `any`, `*`
- `Array`, `Object`, `RegExp`, `Date`, `Function`

<a name="eslint-plugin-jsdoc-rules-no-undefined-types-options-3"></a>
<a name="eslint-plugin-jsdoc-rules-no-undefined-types-options-4"></a>
#### Options

An option object may have the following keys:
Expand Down Expand Up @@ -3671,7 +3688,7 @@ Requires that all functions have a description.
* All functions must have a `@description` tag.
* Every description tag must have a non-empty description that explains the purpose of the method.

<a name="eslint-plugin-jsdoc-rules-require-description-options-4"></a>
<a name="eslint-plugin-jsdoc-rules-require-description-options-5"></a>
#### Options

An options object may have any of the following properties:
Expand Down Expand Up @@ -3865,7 +3882,7 @@ Requires that all functions have examples.
* All functions must have one or more `@example` tags.
* Every example tag must have a non-empty description that explains the method's usage.

<a name="eslint-plugin-jsdoc-rules-require-example-options-5"></a>
<a name="eslint-plugin-jsdoc-rules-require-example-options-6"></a>
#### Options

Has an object option with one optional property:
Expand Down Expand Up @@ -3996,7 +4013,7 @@ function quux () {

Requires a hyphen before the `@param` description.

<a name="eslint-plugin-jsdoc-rules-require-hyphen-before-param-description-options-6"></a>
<a name="eslint-plugin-jsdoc-rules-require-hyphen-before-param-description-options-7"></a>
#### 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"`.
Expand Down Expand Up @@ -4102,7 +4119,7 @@ function quux () {
Checks for presence of jsdoc comments, on class declarations as well as
functions.

<a name="eslint-plugin-jsdoc-rules-require-jsdoc-options-7"></a>
<a name="eslint-plugin-jsdoc-rules-require-jsdoc-options-8"></a>
#### Options

Accepts one optional options object with the following optional keys.
Expand Down Expand Up @@ -5138,7 +5155,7 @@ function quux (foo) {

Requires that all function parameters are documented.

<a name="eslint-plugin-jsdoc-rules-require-param-options-8"></a>
<a name="eslint-plugin-jsdoc-rules-require-param-options-9"></a>
#### Options

An options object accepts one optional property:
Expand Down Expand Up @@ -6065,7 +6082,7 @@ function quux () {

Requires returns are documented.

<a name="eslint-plugin-jsdoc-rules-require-returns-options-9"></a>
<a name="eslint-plugin-jsdoc-rules-require-returns-options-10"></a>
#### Options

- `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
Expand Down
8 changes: 2 additions & 6 deletions src/iterateJsdoc.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,6 @@ const getUtils = (
jsdocNode,
{
tagNamePreference,
additionalTagNames,
allowEmptyNamepaths,
overrideReplacesDocs,
implementsReplacesDocs,
Expand Down Expand Up @@ -89,8 +88,8 @@ const getUtils = (
return isObject && !allowObjectReturn ? ret.replacement : ret;
};

utils.isValidTag = (name) => {
return jsdocUtils.isValidTag(name, additionalTagNames);
utils.isValidTag = (name, definedTags) => {
return jsdocUtils.isValidTag(name, definedTags);
};

utils.hasATag = (name) => {
Expand Down Expand Up @@ -261,9 +260,6 @@ const getSettings = (context) => {
settings.implementsReplacesDocs = _.get(context, 'settings.jsdoc.implementsReplacesDocs');
settings.augmentsExtendsReplacesDocs = _.get(context, 'settings.jsdoc.augmentsExtendsReplacesDocs');

// `check-tag-names` only
settings.additionalTagNames = _.get(context, 'settings.jsdoc.additionalTagNames') || {};

// `check-examples` only
settings.exampleCodeRegex = _.get(context, 'settings.jsdoc.exampleCodeRegex') || null;
settings.rejectExampleCodeRegex = _.get(context, 'settings.jsdoc.rejectExampleCodeRegex') || null;
Expand Down
4 changes: 2 additions & 2 deletions src/jsdocUtils.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,9 +79,9 @@ const getPreferredTagName = (name : string, tagPreference : Object = {}) : strin
return name;
};

const isValidTag = (name : string, additionalTagNames : Object) : boolean => {
const isValidTag = (name : string, definedTags : Array) : boolean => {
const validTagNames = _.keys(tagNames).concat(_.flatten(_.values(tagNames)));
const additionalTags = additionalTagNames.customTags || [];
const additionalTags = definedTags;
const allTags = validTagNames.concat(additionalTags);

return allTags.includes(name);
Expand Down
Loading