Support for @template with JSDoc types

[kevinoid]

Motivation

If JSDoc is configured with closure in tags.dictionaries, the @template tag is supported (to some degree). I would like to lint files using this configuration with eslint-plugin-jsdoc.

Current behavior

With .eslintrc.json:

{
  "env": {"es6": true},
  "extends": ["plugin:jsdoc/recommended"]
}

and jsdoc.conf:

{
  "tags": {
    "allowUnknownTags": false,
    "dictionaries": [
      "jsdoc",
      "closure"
    ]
  }
}

and index.js:

/** Create a Promise resolved with a given value.
 *
 * @template T
 * @param {T} value Value to resolve.
 * @returns {!Promise<T>} Promise resolved to value.
 */
function resolve(value) {
  return Promise.resolve;
}

/** Create a readable stream for the file at a given path.
 *
 * @param {string} path Path of file to read.
 * @returns {!module:fs.ReadStream} Readable stream for file at path.
 */
function createReadStream(path) {
  return require('fs').createReadStream(path);
}

If I run jsdoc -c jsdoc.conf.json index.js, JSDoc generates the documentation without errors.

If I run eslint -f unix index.js it produces the following errors:

/tmp/example/index.js:3:0: Invalid JSDoc tag name "template". [Warning/jsdoc/check-tag-names]
/tmp/example/index.js:4:0: The type 'T' is undefined. [Warning/jsdoc/no-undefined-types]
/tmp/example/index.js:5:0: The type 'T' is undefined. [Warning/jsdoc/no-undefined-types]

3 problems

If I add "rules": {"jsdoc/check-tag-names": ["error", {"definedTags": ["template"]}]} to .eslintrc.json, eslint-plugin-jsdoc will allow @template but does not recognize T which it defines and still produces the following errors:

/tmp/example/index.js:4:0: The type 'T' is undefined. [Warning/jsdoc/no-undefined-types]
/tmp/example/index.js:5:0: The type 'T' is undefined. [Warning/jsdoc/no-undefined-types]

2 problems

If I add "settings": {"jsdoc": {"mode": "typescript"}} to .eslintrc.json, eslint-plugin-jsdoc will recognize @template but now fails to recognize module: types and produces the following errors:

/tmp/example/index.js:14:0: Syntax error in type: !module:fs.ReadStream [Warning/jsdoc/valid-types]

1 problem

Desired behavior

That eslint-plugin-jsdoc would provide a way to recognize both @template and module: types as JSDoc does.

Thanks for considering,
Kevin

[brettz9]

Did you try "settings": {"jsdoc": {"mode": "closure"}} or if that doesn't work for you, then "settings": {"jsdoc": {"mode": "permissive"}}?

[kevinoid]

Bingo! I'm not sure how I missed that. Using closure or permissive mode (along with tagNamePreference to avoid warnings about @returns) works like a charm. The following .eslintrc.json seems to cover the above code without error:

{
  "env": {"es6": true},
  "extends": ["plugin:jsdoc/recommended"],
  "settings": {
    "jsdoc": {
      "mode": "closure",
      "tagNamePreference": {
        "return": "returns"
      }
    }
  }
}

Many thanks!