Skip to content

Commit fd36278

Browse files
committed
feat(check-tag-names and other rules): begin settings.jsdoc.mode; utilize in getPreferredTagName, isValidTag, getTagsByType; fixes part of #356
BREAKING CHANGE: Allowable values: jsdoc|typescript|closure
1 parent 8df4ade commit fd36278

File tree

9 files changed

+414
-56
lines changed

9 files changed

+414
-56
lines changed

.README/README.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,12 @@ You can then selectively add to or override the recommended rules.
8888
- `settings.jsdoc.ignorePrivate` - Disables all rules for the comment block
8989
on which a `@private` tag occurs. Defaults to `false`.
9090

91+
### Mode
92+
93+
- `settings.jsdoc.mode` - Set to `jsdoc` (the default), `typescript`, or `closure`.
94+
Currently is used for checking preferred tag names and in the `check-tag-names`
95+
rule.
96+
9197
### Alias Preference
9298

9399
Use `settings.jsdoc.tagNamePreference` to configure a preferred alias name for a JSDoc tag. The format of the configuration is: `<primary tag name>: <preferred alias name>`, e.g.

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

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -101,14 +101,16 @@ yield
101101
```
102102

103103
For [TypeScript](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc)
104-
(or Closure), one may also use the following:
104+
(or Closure), when `settings.jsdoc.mode` is set to `typescript` or `closure`,
105+
one may also use the following:
105106

106107
```
107108
template
108109
```
109110

110111
And for [Closure](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#nosideeffects-modifies-thisarguments),
111-
one may also use:
112+
when `settings.jsdoc.mode` is set to `closure`, one may use the following (in
113+
addition to the jsdoc and TypeScript tags):
112114

113115
```
114116
define
@@ -128,7 +130,6 @@ polymerBehavior
128130
preserve
129131
struct
130132
suppress
131-
template
132133
unrestricted
133134
```
134135

@@ -138,7 +139,7 @@ Note that the tags indicated as replacements in `settings.jsdoc.tagNamePreferenc
138139

139140
##### `definedTags`
140141

141-
Use an array of `definedTags` strings to configure additional, allowed JSDoc tags.
142+
Use an array of `definedTags` strings to configure additional, allowed tags.
142143
The format is as follows:
143144

144145
```json
@@ -152,6 +153,6 @@ The format is as follows:
152153
|Context|everywhere|
153154
|Tags|N/A|
154155
|Options|`definedTags`|
155-
|Settings|`tagNamePreference`|
156+
|Settings|`tagNamePreference`, `mode`|
156157

157158
<!-- assertions checkTagNames -->

README.md

Lines changed: 251 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ JSDoc linting rules for ESLint.
1313
* [Configuration](#eslint-plugin-jsdoc-configuration)
1414
* [Settings](#eslint-plugin-jsdoc-settings)
1515
* [Allow `@private` to disable rules for that comment block](#eslint-plugin-jsdoc-settings-allow-private-to-disable-rules-for-that-comment-block)
16+
* [Mode](#eslint-plugin-jsdoc-settings-mode)
1617
* [Alias Preference](#eslint-plugin-jsdoc-settings-alias-preference)
1718
* [`@override`/`@augments`/`@extends`/`@implements` Without Accompanying `@param`/`@description`/`@example`/`@returns`](#eslint-plugin-jsdoc-settings-override-augments-extends-implements-without-accompanying-param-description-example-returns)
1819
* [Settings to Configure `check-types` and `no-undefined-types`](#eslint-plugin-jsdoc-settings-settings-to-configure-check-types-and-no-undefined-types)
@@ -128,6 +129,13 @@ You can then selectively add to or override the recommended rules.
128129
- `settings.jsdoc.ignorePrivate` - Disables all rules for the comment block
129130
on which a `@private` tag occurs. Defaults to `false`.
130131

132+
<a name="eslint-plugin-jsdoc-settings-mode"></a>
133+
### Mode
134+
135+
- `settings.jsdoc.mode` - Set to `jsdoc` (the default), `typescript`, or `closure`.
136+
Currently is used for checking preferred tag names and in the `check-tag-names`
137+
rule.
138+
131139
<a name="eslint-plugin-jsdoc-settings-alias-preference"></a>
132140
### Alias Preference
133141

@@ -1495,14 +1503,16 @@ yield
14951503
```
14961504

14971505
For [TypeScript](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc)
1498-
(or Closure), one may also use the following:
1506+
(or Closure), when `settings.jsdoc.mode` is set to `typescript` or `closure`,
1507+
one may also use the following:
14991508

15001509
```
15011510
template
15021511
```
15031512

15041513
And for [Closure](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#nosideeffects-modifies-thisarguments),
1505-
one may also use:
1514+
when `settings.jsdoc.mode` is set to `closure`, one may use the following (in
1515+
addition to the jsdoc and TypeScript tags):
15061516

15071517
```
15081518
define
@@ -1522,7 +1532,6 @@ polymerBehavior
15221532
preserve
15231533
struct
15241534
suppress
1525-
template
15261535
unrestricted
15271536
```
15281537

@@ -1534,7 +1543,7 @@ Note that the tags indicated as replacements in `settings.jsdoc.tagNamePreferenc
15341543
<a name="eslint-plugin-jsdoc-rules-check-tag-names-options-2-definedtags"></a>
15351544
##### <code>definedTags</code>
15361545

1537-
Use an array of `definedTags` strings to configure additional, allowed JSDoc tags.
1546+
Use an array of `definedTags` strings to configure additional, allowed tags.
15381547
The format is as follows:
15391548

15401549
```json
@@ -1548,7 +1557,7 @@ The format is as follows:
15481557
|Context|everywhere|
15491558
|Tags|N/A|
15501559
|Options|`definedTags`|
1551-
|Settings|`tagNamePreference`|
1560+
|Settings|`tagNamePreference`, `mode`|
15521561

15531562
The following patterns are considered problems:
15541563

@@ -1709,6 +1718,162 @@ function quux () {
17091718
}
17101719
// Settings: {"jsdoc":{"tagNamePreference":{"abc":"abcd"}}}
17111720
// Message: Invalid JSDoc tag (preference). Replace "abc" JSDoc tag with "abcd".
1721+
1722+
/**
1723+
* @modifies
1724+
* @abstract
1725+
* @access
1726+
* @alias
1727+
* @async
1728+
* @augments
1729+
* @author
1730+
* @borrows
1731+
* @callback
1732+
* @class
1733+
* @classdesc
1734+
* @constant
1735+
* @constructs
1736+
* @copyright
1737+
* @default
1738+
* @deprecated
1739+
* @description
1740+
* @enum
1741+
* @event
1742+
* @example
1743+
* @exports
1744+
* @external
1745+
* @file
1746+
* @fires
1747+
* @function
1748+
* @generator
1749+
* @global
1750+
* @hideconstructor
1751+
* @ignore
1752+
* @implements
1753+
* @inheritdoc
1754+
* @inner
1755+
* @instance
1756+
* @interface
1757+
* @kind
1758+
* @lends
1759+
* @license
1760+
* @listens
1761+
* @member
1762+
* @memberof
1763+
* @memberof!
1764+
* @mixes
1765+
* @mixin
1766+
* @module
1767+
* @name
1768+
* @namespace
1769+
* @override
1770+
* @package
1771+
* @param
1772+
* @private
1773+
* @property
1774+
* @protected
1775+
* @public
1776+
* @readonly
1777+
* @requires
1778+
* @returns
1779+
* @see
1780+
* @since
1781+
* @static
1782+
* @summary
1783+
* @this
1784+
* @throws
1785+
* @todo
1786+
* @tutorial
1787+
* @type
1788+
* @typedef
1789+
* @variation
1790+
* @version
1791+
* @yields
1792+
*/
1793+
function quux (foo) {}
1794+
// Settings: {"jsdoc":{"mode":"badMode"}}
1795+
// Message: Unrecognized value `badMode` for `settings.jsdoc.mode`.
1796+
1797+
/**
1798+
* @modifies
1799+
* @abstract
1800+
* @access
1801+
* @alias
1802+
* @async
1803+
* @augments
1804+
* @author
1805+
* @borrows
1806+
* @callback
1807+
* @class
1808+
* @classdesc
1809+
* @constant
1810+
* @constructs
1811+
* @copyright
1812+
* @default
1813+
* @deprecated
1814+
* @description
1815+
* @enum
1816+
* @event
1817+
* @example
1818+
* @exports
1819+
* @external
1820+
* @file
1821+
* @fires
1822+
* @function
1823+
* @generator
1824+
* @global
1825+
* @hideconstructor
1826+
* @ignore
1827+
* @implements
1828+
* @inheritdoc
1829+
* @inner
1830+
* @instance
1831+
* @interface
1832+
* @kind
1833+
* @lends
1834+
* @license
1835+
* @listens
1836+
* @member
1837+
* @memberof
1838+
* @memberof!
1839+
* @mixes
1840+
* @mixin
1841+
* @module
1842+
* @name
1843+
* @namespace
1844+
* @override
1845+
* @package
1846+
* @param
1847+
* @private
1848+
* @property
1849+
* @protected
1850+
* @public
1851+
* @readonly
1852+
* @requires
1853+
* @returns
1854+
* @see
1855+
* @since
1856+
* @static
1857+
* @summary
1858+
* @this
1859+
* @throws
1860+
* @todo
1861+
* @tutorial
1862+
* @type
1863+
* @typedef
1864+
* @variation
1865+
* @version
1866+
* @yields
1867+
* @template
1868+
*/
1869+
function quux (foo) {}
1870+
// Message: Invalid JSDoc tag name "template".
1871+
1872+
/**
1873+
* @externs
1874+
*/
1875+
function quux (foo) {}
1876+
// Message: Invalid JSDoc tag name "externs".
17121877
````
17131878

17141879
The following patterns are not considered problems:
@@ -1833,6 +1998,87 @@ function quux (foo) {
18331998
*/
18341999
function quux (foo) {}
18352000

2001+
/**
2002+
* @modifies
2003+
* @abstract
2004+
* @access
2005+
* @alias
2006+
* @async
2007+
* @augments
2008+
* @author
2009+
* @borrows
2010+
* @callback
2011+
* @class
2012+
* @classdesc
2013+
* @constant
2014+
* @constructs
2015+
* @copyright
2016+
* @default
2017+
* @deprecated
2018+
* @description
2019+
* @enum
2020+
* @event
2021+
* @example
2022+
* @exports
2023+
* @external
2024+
* @file
2025+
* @fires
2026+
* @function
2027+
* @generator
2028+
* @global
2029+
* @hideconstructor
2030+
* @ignore
2031+
* @implements
2032+
* @inheritdoc
2033+
* @inner
2034+
* @instance
2035+
* @interface
2036+
* @kind
2037+
* @lends
2038+
* @license
2039+
* @listens
2040+
* @member
2041+
* @memberof
2042+
* @memberof!
2043+
* @mixes
2044+
* @mixin
2045+
* @module
2046+
* @name
2047+
* @namespace
2048+
* @override
2049+
* @package
2050+
* @param
2051+
* @private
2052+
* @property
2053+
* @protected
2054+
* @public
2055+
* @readonly
2056+
* @requires
2057+
* @returns
2058+
* @see
2059+
* @since
2060+
* @static
2061+
* @summary
2062+
* @this
2063+
* @throws
2064+
* @todo
2065+
* @tutorial
2066+
* @type
2067+
* @typedef
2068+
* @variation
2069+
* @version
2070+
* @yields
2071+
* @template
2072+
*/
2073+
function quux (foo) {}
2074+
// Settings: {"jsdoc":{"mode":"typescript"}}
2075+
2076+
/**
2077+
* @externs
2078+
*/
2079+
function quux (foo) {}
2080+
// Settings: {"jsdoc":{"mode":"closure"}}
2081+
18362082
/**
18372083
*
18382084
*/

0 commit comments

Comments
 (0)