valid-jsdoc @return validation doesn't take async into account

Tell us about your environment

• ESLint Version: 3.7.1
• Node Version: 7.0.0 nightly
• npm Version: 3.10.8

What parser (default, Babel-ESLint, etc.) are you using? Default

Please show your full configuration:

{
    "extends": "eslint:recommended",
    "env": {
        "node": true,
        "es6": true
    },
    "parserOptions": {
        "ecmaVersion": 2017
    },
    "rules": {
        "no-extra-parens": ["warn", "all", {
            "nestedBinaryExpressions": false
        }],
        "valid-jsdoc": ["error", {
            "requireReturn": false
        }],

        "accessor-pairs": "warn",
        "array-callback-return": "error",
        "complexity": "warn",
        "consistent-return": "error",
        "curly": ["error", "multi-line", "consistent"],
        "dot-location": ["error", "property"],
        "dot-notation": "error",
        "eqeqeq": "error",
        "no-empty-function": "error",
        "no-floating-decimal": "error",
        "no-implied-eval": "error",
        "no-invalid-this": "error",
        "no-lone-blocks": "error",
        "no-multi-spaces": "error",
        "no-new-func": "error",
        "no-new-wrappers": "error",
        "no-new": "error",
        "no-octal-escape": "error",
        "no-return-assign": "error",
        "no-self-compare": "error",
        "no-sequences": "error",
        "no-throw-literal": "error",
        "no-unmodified-loop-condition": "error",
        "no-unused-expressions": "error",
        "no-useless-call": "error",
        "no-useless-concat": "error",
        "no-useless-escape": "error",
        "no-void": "error",
        "no-warning-comments": "warn",
        "wrap-iife": "error",
        "yoda": "error",

        "no-label-var": "error",
        "no-shadow": "error",
        "no-undef-init": "error",

        "callback-return": "error",
        "handle-callback-err": "error",
        "no-mixed-requires": "error",
        "no-new-require": "error",
        "no-path-concat": "error",
        "no-process-env": "error",

        "array-bracket-spacing": "error",
        "block-spacing": "error",
        "brace-style": ["error", "1tbs", { "allowSingleLine": true }],
        "camelcase": "error",
        "comma-dangle": "error",
        "comma-spacing": "error",
        "comma-style": "error",
        "computed-property-spacing": "error",
        "consistent-this": "error",
        "eol-last": "error",
        "func-names": "error",
        "func-style": ["error", "declaration", { "allowArrowFunctions": true }],
        "id-length": ["error", { "exceptions": ["i", "j", "a", "b"] }],
        "indent": ["error", "tab", { "SwitchCase": 1 }],
        "key-spacing": "error",
        "keyword-spacing": ["error", {
            "overrides": {
                "if": { "after": false },
                "for": { "after": false },
                "while": { "after": false },
                "catch": { "after": false },
                "switch": { "after": false }
            }
        }],
        "max-depth": "error",
        "max-len": ["error", 120, 2],
        "max-nested-callbacks": ["error", { "max": 4 }],
        "max-statements-per-line": ["error", { "max": 2 }],
        "new-cap": "error",
        "newline-per-chained-call": ["error", { "ignoreChainWithDepth": 3 }],
        "no-array-constructor": "error",
        "no-bitwise": "warn",
        "no-inline-comments": "error",
        "no-lonely-if": "error",
        "no-mixed-operators": "error",
        "no-multiple-empty-lines": ["error", { "max": 2, "maxEOF": 1, "maxBOF": 0 }],
        "no-new-object": "error",
        "no-spaced-func": "error",
        "no-trailing-spaces": "error",
        "no-unneeded-ternary": "error",
        "no-whitespace-before-property": "error",
        "object-curly-newline": "error",
        "object-curly-spacing": ["error", "always"],
        "operator-assignment": "error",
        "operator-linebreak": ["error", "after"],
        "padded-blocks": ["error", "never"],
        "quote-props": ["error", "as-needed"],
        "quotes": ["error", "single", { "avoidEscape": true, "allowTemplateLiterals": true }],
        "semi-spacing": "error",
        "semi": "error",
        "space-before-blocks": "error",
        "space-before-function-paren": ["error", "never"],
        "space-in-parens": "error",
        "space-infix-ops": "error",
        "space-unary-ops": "error",
        "spaced-comment": "error",
        "unicode-bom": "error",

        "arrow-body-style": "error",
        "arrow-spacing": "error",
        "no-duplicate-imports": "error",
        "no-useless-computed-key": "error",
        "no-useless-constructor": "error",
        "prefer-arrow-callback": "error",
        "prefer-rest-params": "error",
        "prefer-spread": "error",
        "prefer-template": "error",
        "rest-spread-spacing": "error",
        "template-curly-spacing": "error",
        "yield-star-spacing": "error"
    }
}

What did you do? Please include the actual source code causing the issue.

/**
 * Runs the command
 * @param {Message} message - The message the command is being run for
 * @param {string[]} args - The arguments for the command, or the matches from a pattern
 * @param {boolean} fromPattern - Whether or not the command is being run from a pattern match or not
 * @return {Promise<CommandResult|string[]|string>} The result of running the command
 */
async run(message, args, fromPattern) { // eslint-disable-line no-unused-vars
    throw new Error(`${this.constructor.name} doesn't have a run() method.`);
}

What did you expect to happen? The @return tag should accept returning Promises from async functions, regardless of the presence of a return statement. All async functions return Promises, always.

What actually happened? Please include the actual, raw output from ESLint. ESLint outputs the error, Unexpected @return tag; function has no return statement..

[basicdays]

I’d be a fan of that. I have return undefined; //hack valid-jsdoc in a lot of my async functions just so I can still have jsdoc linting but to suppress this error.

[morficus]

Would anyone be interested in re-opening this? I think what @vitorbal lays out would be great for async and generator functions.