Merge branch 'master' into 177-support-ts-param-props

* master: (22 commits)
  docs(code comment): make reference to @template being non-standard tag docs(contributing): clarify reasons for adhering to AngularJS syntax testing: add back timeouts as still occasionally timing out
  docs(contributing): note on merging
  chore: add `.ncurc.js` to avoid `npm-check-updates` indicating `peerDependencies` (with `eslint`) having update available
  build: add test for eslint@5 in ci
  chore: update `eslint` in `peerDependencies` to 6.0.0
  chore: bump .travis.yml to use node 10 over 6
  docs: generate docs
  chore: add `.ncurc.js` to avoid `npm-check-updates` indicating `peerDependencies` (with `eslint`) having update available
  fix(require-jsdoc): with eslint 6, we can't use schema for defaults, so revert to old approach chore(linting): update eslint devDep testing: avoid timeout (not an issue anymore with eslint 6) testing(check-examples): use absolute paths with `matchingFileName` (used with `getConfigForFile`/`Linter`) per eslint 6 testing(check-examples): use a simple `matchingFileName` file which doesn't have problem with loading `babel-eslint` in eslint 6 as does our config testing(require-param): use absolute paths with `parser` per eslint 6
  docs(testing): add info on test coverage testing: increase timeout to 7000ms for rare occasion goes over 5000 testing: require `check-coverage` and set branches/lines/statements to 95% until `exportParser.js` coverage may be added
  docs: generate docs
  Add a negative test case for interface classes in require-returns-check
  docs: generate docs
  Skip interface class methods in require-returns-check
  docs: generate docs
  Add invalid test cases for generic types
  Simplify by using `flatMap`
  docs: generate docs
  Parse multiple template types in one tag
  docs: generate docs
  ...

Author: brettz9

.gitignore

@@ -11,3 +11,4 @@ package-lock.json
 !.npmignore
 !.README
 !.travis.yml
+!.ncurc.js

.ncurc.js

@@ -0,0 +1,6 @@
+module.exports = {
+  // Whitelist all for checking besides `peer` which indicates
+  //   somewhat older versions of `eslint` we still support even
+  //   while our devDeps point to a more recent version
+  "dep": "prod,dev,optional,bundle"
+};

.travis.yml

@@ -1,17 +1,32 @@
 language: node_js
 node_js:
-  - node
+  - 12
+  - 10
   - 8
   - 6
 before_install:
   - npm config set depth 0
+before_script:
+  - 'if [ -n "${ESLINT-}" ]; then npm install --no-save "eslint@${ESLINT}" ; fi'
 notifications:
   email: false
 sudo: false
 script:
   - npm run test
-  - npm run lint
+  - 'if [ -n "${LINT-}" ]; then npm run lint; fi'
   - npm run build
+env:
+  matrix:
+    - ESLINT=6
+    - ESLINT=5
+matrix:
+  fast_finish: true
+  include:
+    - node_js: 'lts/*'
+      env: LINT=true
+  exclude:
+    - node_js: 6
+      env: ESLINT=6
 after_success:
   - export NODE_ENV=production
   - npm run build

CONTRIBUTING.md

@@ -43,6 +43,11 @@ See ESLint's [RuleTester](https://eslint.org/docs/developer-guide/nodejs-api#rul
 for more on the allowable properties (e.g., `code`, `errors` (for invalid rules),
 `options`, `settings`, etc.).
 
+Note that besides `npm test`, there is `npm run test-cov` which shows more detailed
+information on coverage. Coverage should be maintained at 100%, and if there are
+a few guards in place for future use, the code block in question can be ignored
+by being preceded by `/* istanbul ignore next */`.
+
 ## Requirements for PRs
 
 PRs should be mergeable, [rebasing](https://git-scm.com/book/en/v2/Git-Branching-Rebasing)
@@ -53,3 +58,12 @@ can better show a progression of features.
 
 Commit messages should be worded clearly and the reason for any PR made clear
 by linking to an issue or giving a full description of what it achieves.
+
+## Merging
+
+We use [semantic-release](https://github.com/semantic-release/semantic-release)
+for preparing releases, so the commit messages (or at least the merge that
+brings them into `master`) must follow the
+[AngularJS commit guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines) with a special format such as `feat: describe new feature`
+in order for the releasing to occur and for the described items to be added
+to the release notes.

README.md

@@ -678,7 +678,7 @@ function quux () {}
 function quux2 () {
 
 }
-// Settings: {"jsdoc":{"matchingFileName":"test/jsdocUtils.js"}}
+// Settings: {"jsdoc":{"matchingFileName":"/Users/brett/eslint-plugin-jsdoc/test/rules/data/test.js"}}
 // Message: @example error (semi): Missing semicolon.
 
 /**
@@ -2791,6 +2791,35 @@ function quux(foo, bar, baz) {
 // Settings: {"jsdoc":{"preferredTypes":{"hertype":{"replacement":false},"histype":"HisType"}}}
 // Options: [{"definedTypes":["MyType"],"preferredTypesDefined":true}]
 // Message: The type 'HerType' is undefined.
+
+class Foo {
+  /**
+   * @return {TEMPLATE_TYPE}
+   */
+  bar () {
+  }
+}
+// Message: The type 'TEMPLATE_TYPE' is undefined.
+
+class Foo {
+  /**
+   * @return {TEMPLATE_TYPE}
+   */
+  invalidTemplateReference () {
+  }
+}
+
+/**
+ * @template TEMPLATE_TYPE
+ */
+class Bar {
+  /**
+   * @return {TEMPLATE_TYPE}
+   */
+  validTemplateReference () {
+  }
+}
+// Message: The type 'TEMPLATE_TYPE' is undefined.
 ````
 
 The following patterns are not considered problems:
@@ -2941,6 +2970,29 @@ function quux(foo, bar, baz) {
 }
 // Settings: {"jsdoc":{"preferredTypes":{"hertype":{"replacement":"HerType<>"},"histype":"HisType.<>"}}}
 // Options: [{"definedTypes":["MyType"],"preferredTypesDefined":true}]
+
+/**
+ * @template TEMPLATE_TYPE
+ */
+class Foo {
+  /**
+   * @return {TEMPLATE_TYPE}
+   */
+  bar () {
+  }
+}
+
+/**
+ * @template TEMPLATE_TYPE_A, TEMPLATE_TYPE_B
+ */
+class Foo {
+  /**
+   * @param {TEMPLATE_TYPE_A} baz
+   * @return {TEMPLATE_TYPE_B}
+   */
+  bar (baz) {
+  }
+}
 ````
 
 
@@ -5016,6 +5068,15 @@ const language = {
   }
 }
 // Message: JSDoc @returns declaration present but return expression not available in function.
+
+class Foo {
+  /**
+   * @returns {string}
+   */
+  bar () {
+  }
+}
+// Message: JSDoc @returns declaration present but return expression not available in function.
 ````
 
 The following patterns are not considered problems:
@@ -5104,6 +5165,17 @@ function quux () {
 function quux () {
 }
 
+/**
+ * @interface
+ */
+class Foo {
+  /**
+   * @returns {string}
+   */
+  bar () {
+  }
+}
+
 /**
  * @returns {undefined} Foo.
  */

package.json

@@ -24,7 +24,7 @@
     "babel-plugin-add-module-exports": "^1.0.2",
     "babel-plugin-istanbul": "^5.1.4",
     "chai": "^4.2.0",
-    "eslint": "^5.14.1",
+    "eslint": "^6.0.0",
     "eslint-config-canonical": "^17.1.1",
     "gitdown": "^2.5.8",
     "glob": "^7.1.4",
@@ -54,7 +54,7 @@
   "main": "./dist/index.js",
   "name": "eslint-plugin-jsdoc",
   "peerDependencies": {
-    "eslint": ">=5.16.0"
+    "eslint": "^5.0.0 || ^6.0.0"
   },
   "repository": {
     "type": "git",
@@ -65,8 +65,8 @@
     "build": "rm -fr ./dist && NODE_ENV=production babel ./src --out-dir ./dist --copy-files --source-maps",
     "create-readme": "gitdown ./.README/README.md --output-file ./README.md && npm run add-assertions",
     "lint": "eslint ./src ./test",
-    "test-cov": "BABEL_ENV=test nyc mocha --recursive --require @babel/register --reporter progress --timeout 5000",
-    "test": "BABEL_ENV=test nyc --reporter text-summary mocha --recursive --require @babel/register --reporter progress --timeout 5000"
+    "test-cov": "BABEL_ENV=test nyc mocha --recursive --require @babel/register --reporter progress --timeout 7000",
+    "test": "BABEL_ENV=test nyc --reporter text-summary mocha --recursive --require @babel/register --reporter progress --timeout 7000"
   },
   "nyc": {
     "require": [
@@ -76,7 +76,12 @@
     "instrument": false,
     "include": [
       "src/"
-    ]
+    ],
+    "check-coverage": true,
+    "branches": 95,
+    "lines": 95,
+    "functions": 100,
+    "statements": 95
   },
   "version": "1.0.0"
 }

src/iterateJsdoc.js

@@ -189,20 +189,23 @@ const curryUtils = (
     return false;
   };
 
-  utils.classHasTag = (tagName) => {
+  utils.getClassJsdoc = () => {
     const classNode = utils.getClassNode();
     const classJsdocNode = getJSDocComment(sourceCode, classNode);
 
     if (classJsdocNode) {
       const indent = _.repeat(' ', classJsdocNode.loc.start.column);
-      const classJsdoc = parseComment(classJsdocNode, indent);
 
-      if (jsdocUtils.hasTag(classJsdoc, tagName)) {
-        return true;
-      }
+      return parseComment(classJsdocNode, indent);
     }
 
-    return false;
+    return null;
+  };
+
+  utils.classHasTag = (tagName) => {
+    const classJsdoc = utils.getClassJsdoc();
+
+    return classJsdoc && jsdocUtils.hasTag(classJsdoc, tagName);
   };
 
   utils.forEachTag = (tagName, arrayHandler) => {

src/jsdocUtils.js

@@ -467,6 +467,22 @@ const isInlineTag = (tag) => {
 };
 */
 
+/**
+ * Parses GCC Generic/Template types
+ *
+ * @see {https://github.com/google/closure-compiler/wiki/Generic-Types}
+ * @param {JsDocTag} tag
+ * @returns {Array<string>}
+ */
+const parseClosureTemplateTag = (tag) => {
+  return tag.source
+    .split('@template')[1]
+    .split(',')
+    .map((type) => {
+      return type.trim();
+    });
+};
+
 export default {
   getFunctionParameterNames,
   getJsdocParameterNames,
@@ -480,5 +496,6 @@ export default {
   isNamepathTag,
   isPotentiallyEmptyNamepathTag,
   isTagWithType,
-  isValidTag
+  isValidTag,
+  parseClosureTemplateTag
 };

src/rules/newlineAfterDescription.js

@@ -56,12 +56,12 @@ export default iterateJsdoc(({
 }, {
   meta: {
     fixable: 'whitespace',
+    schema: [
+      {
+        enum: ['always', 'never'],
+        type: 'string'
+      }
+    ],
     type: 'layout'
-  },
-  schema: [
-    {
-      enum: ['always'],
-      type: 'string'
-    }
-  ]
+  }
 });

src/rules/noUndefinedTypes.js

@@ -3,6 +3,7 @@ import 'flat-map-polyfill';
 import _ from 'lodash';
 import {parse as parseType, traverse} from 'jsdoctypeparser';
 import iterateJsdoc, {parseComment} from '../iterateJsdoc';
+import jsdocUtils from '../jsdocUtils';
 
 const extraTypes = [
   'null', 'undefined', 'string', 'boolean', 'object',
@@ -67,6 +68,18 @@ export default iterateJsdoc(({
     })
     .value();
 
+  let closureGenericTypes = [];
+  const classJsdoc = utils.getClassJsdoc();
+  if (classJsdoc && classJsdoc.tags) {
+    closureGenericTypes = classJsdoc.tags
+      .filter((tag) => {
+        return tag.tag === 'template';
+      })
+      .flatMap((tag) => {
+        return jsdocUtils.parseClosureTemplateTag(tag);
+      });
+  }
+
   const allDefinedTypes = globalScope.variables.map((variable) => {
     return variable.name;
   })
@@ -89,7 +102,8 @@ export default iterateJsdoc(({
     .concat(extraTypes)
     .concat(typedefDeclarations)
     .concat(definedTypes)
-    .concat(definedPreferredTypes);
+    .concat(definedPreferredTypes)
+    .concat(closureGenericTypes);
 
   const jsdocTags = utils.filterTags((tag) => {
     return utils.isTagWithType(tag.tag);