feat(check-tag-names): for "closure" mode, prefer "return" over "returns"; fixes part of #356

Author: brettz9

.README/README.md

@@ -135,7 +135,7 @@ how many line breaks to add when a block is missing.
   containing both JavaScript and TypeScript, you can also use [`overrides`](https://eslint.org/docs/user-guide/configuring). You may also set to `"permissive"` to
   try to be as accommodating to any of the styles, but this is not recommended.
   Currently is used for the following:
-  - Determine valid tags for `check-tag-names`
+  - Determine valid tags and aliases for `check-tag-names`
   - Only check `@template` in `no-undefined-types` for types in "closure" and
     "typescript" modes
   - For type-checking rules, determine which tags will be checked for types

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

@@ -126,7 +126,8 @@ template
 
 And for [Closure](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler),
 when `settings.jsdoc.mode` is set to `closure`, one may use the following (in
-addition to the jsdoc and TypeScript tags):
+addition to the jsdoc and TypeScript tags–though replacing `returns` with
+`return`):
 
 ```
 define (synonym of `const` per jsdoc source)

.README/rules/valid-types.md

@@ -10,7 +10,8 @@ Also impacts behaviors on namepath (or event)-defining and pointing tags:
     `@class`, `@constructor`, `@constant`, `@const`,
     `@function`, `@func`, `@method`, `@interface`, `@member`, `@var`,
     `@mixin`, `@namespace`
-1. Name(path)-pointing tags requiring namepath: `@alias`, `@augments`, `@extends`, `@lends`, `@memberof`, `@memberof!`, `@mixes`, `@this`
+1. Name(path)-pointing tags requiring namepath: `@alias`, `@augments`,
+    `@extends`, `@lends`, `@memberof`, `@memberof!`, `@mixes`, `@this`
 1. Name(path)-pointing tags (which may have value without namepath or their
     namepath can be expressed elsewhere on the block): `@listens`, `@fires`,
     `@emits`, and `@modifies`

README.md

@@ -193,7 +193,7 @@ how many line breaks to add when a block is missing.
   containing both JavaScript and TypeScript, you can also use [`overrides`](https://eslint.org/docs/user-guide/configuring). You may also set to `"permissive"` to
   try to be as accommodating to any of the styles, but this is not recommended.
   Currently is used for the following:
-  - Determine valid tags for `check-tag-names`
+  - Determine valid tags and aliases for `check-tag-names`
   - Only check `@template` in `no-undefined-types` for types in "closure" and
     "typescript" modes
   - For type-checking rules, determine which tags will be checked for types
@@ -2631,7 +2631,8 @@ template
 
 And for [Closure](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler),
 when `settings.jsdoc.mode` is set to `closure`, one may use the following (in
-addition to the jsdoc and TypeScript tags):
+addition to the jsdoc and TypeScript tags–though replacing `returns` with
+`return`):
 
 ```
 define (synonym of `const` per jsdoc source)
@@ -2863,6 +2864,13 @@ function quux () {
 // Settings: {"jsdoc":{"tagNamePreference":{"abc":"abcd"}}}
 // Message: Invalid JSDoc tag (preference). Replace "abc" JSDoc tag with "abcd".
 
+/**
+ * @returns
+ */
+function quux (foo) {}
+// Settings: {"jsdoc":{"mode":"closure"}}
+// Message: Invalid JSDoc tag (preference). Replace "returns" JSDoc tag with "return".
+
 /** 
  * @modifies
  * @abstract
@@ -3071,6 +3079,17 @@ function quux (foo) {
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"param":"baz","returns":{"message":"Prefer `bar`","replacement":"bar"},"todo":false}}}
 
+/**
+ * @returns
+ */
+function quux (foo) {}
+
+/**
+ * @return
+ */
+function quux (foo) {}
+// Settings: {"jsdoc":{"mode":"closure"}}
+
 /** 
  * @modifies
  * @abstract
@@ -13214,7 +13233,8 @@ Also impacts behaviors on namepath (or event)-defining and pointing tags:
     `@class`, `@constructor`, `@constant`, `@const`,
     `@function`, `@func`, `@method`, `@interface`, `@member`, `@var`,
     `@mixin`, `@namespace`
-1. Name(path)-pointing tags requiring namepath: `@alias`, `@augments`, `@extends`, `@lends`, `@memberof`, `@memberof!`, `@mixes`, `@this`
+1. Name(path)-pointing tags requiring namepath: `@alias`, `@augments`,
+    `@extends`, `@lends`, `@memberof`, `@memberof!`, `@mixes`, `@this`
 1. Name(path)-pointing tags (which may have value without namepath or their
     namepath can be expressed elsewhere on the block): `@listens`, `@fires`,
     `@emits`, and `@modifies`

src/jsdocUtils.js

@@ -231,7 +231,9 @@ const getPreferredTagName = (
 
   // Allow keys to have a 'tag ' prefix to avoid upstream bug in ESLint
   // that disallows keys that conflict with Object.prototype,
-  // e.g. 'tag constructor' for 'constructor' (#537)
+  // e.g. 'tag constructor' for 'constructor':
+  // https://github.com/eslint/eslint/issues/13289
+  // https://github.com/gajus/eslint-plugin-jsdoc/issues/537
   const tagPreferenceFixed = _.mapKeys(tagPreference, (value, key) => {
     return key.replace('tag ', '');
   });

src/tagNames.js

@@ -144,13 +144,17 @@ const undocumentedClosureTags = {
 };
 
 const {
-  // eslint-disable-next-line no-unused-vars
+  /* eslint-disable no-unused-vars */
   inheritdoc,
-  ...typeScriptTagsNoInheritdoc
+
+  // Will be inverted to prefer `return`
+  returns,
+  /* eslint-enable no-unused-vars */
+  ...typeScriptTagsInClosure
 } = typeScriptTags;
 
 const closureTags = {
-  ...typeScriptTagsNoInheritdoc,
+  ...typeScriptTagsInClosure,
   ...undocumentedClosureTags,
 
   // From https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler
@@ -180,6 +184,10 @@ const closureTags = {
   // Defined as a synonym of `interface` in jsdoc `definitions.js`
   record: [],
 
+  return: [
+    'returns',
+  ],
+
   struct: [],
   suppress: [],
 

test/rules/assertions/checkTagNames.js

@@ -503,6 +503,30 @@ export default {
         },
       },
     },
+    {
+      code: `
+      /**
+       * @returns
+       */
+      function quux (foo) {}
+      `,
+      errors: [
+        {
+          message: 'Invalid JSDoc tag (preference). Replace "returns" JSDoc tag with "return".',
+        },
+      ],
+      output: `
+      /**
+       * @return
+       */
+      function quux (foo) {}
+      `,
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
     {
       code: `${ALL_JSDOC_TAGS_COMMENT}\nfunction quux (foo) {}`,
       errors: [
@@ -619,6 +643,27 @@ export default {
         },
       },
     },
+    {
+      code: `
+      /**
+       * @returns
+       */
+      function quux (foo) {}
+      `,
+    },
+    {
+      code: `
+      /**
+       * @return
+       */
+      function quux (foo) {}
+      `,
+      settings: {
+        jsdoc: {
+          mode: 'closure',
+        },
+      },
+    },
     {
       code: `${ALL_JSDOC_TAGS_COMMENT}\nfunction quux (foo) {}`,
     },