5.0.0-alpha.3: valid-jsdoc unexpectedly expects returns for async functions, even with requireReturn: false

[Standard8]

Tell us about your environment

• ESLint Version: 5.0.0-alpha.3
• Node Version: 8.11.2
• npm Version: 5.6.0

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

Please show your full configuration:

Configuration

module.exports = {
  "rules": {
  },
  "env": {
    "es6": true
  },
  "parserOptions": {
    "ecmaVersion": 9,
  },
  "rules": {
    "valid-jsdoc": ["error", {
      "prefer": {
	"return": "returns",
      },
      "requireReturn": false,
      "requireReturnDescription": false,
    }]
  }
};

What did you do? Please include the actual source code causing the issue, as well as the command that you used to run ESLint.

/**                                                                                                                                                       
 * A comment.                                                                                                                                             
 */
async function foo() {
  if (!this.bar) {
    return;
  }

  await this.bar();
}

./node_modules/.bin/eslint eslint5.0test.js

What did you expect to happen?

No failures

What actually happened? Please include the actual, raw output from ESLint.

eslint4.0test.js
  1:1  error  Missing JSDoc @returns for function  valid-jsdoc

✖ 1 problem (1 error, 0 warnings)

This is a possible regression from #10161

[Standard8]

Now I'm having another look at #10161, I'm seeing that since that has been implemented, async functions must always have a @returns statement in the jsdoc, regardless of the requireReturn value.

For a function that is async the fact it returns a promise is implicit in its definition. Therefore, documentation wise, it could be treated the same as a function that returns nothing.

Unfortunately, I'm not quite seeing how making this optional could fit into the current configuration.

So ideas here would be appreciated, /cc @not-an-aardvark @rachx

[rachx]

For a function that is async the fact it returns a promise is implicit in its definition. Therefore, documentation wise, it could be treated the same as a function that returns nothing.

In the original issue, some users suggested that with requireReturn: false, it should also allow them to add jsdoc descriptions as async functions returns a promise.

To make it optional for async function just like constructors and support both preferences, how about check if it is not an async function before reporting missing jsdocs?

eslint/lib/rules/valid-jsdoc.js

Lines 407 to 420 in e0a0418

	// check for functions missing @returns
	if (!isOverride && !hasReturns && !hasConstructor && !isInterface &&
	node.parent.kind !== "get" && node.parent.kind !== "constructor" &&
	node.parent.kind !== "set" && !isTypeClass(node)) {
	if (requireReturn || functionData.returnPresent) {
	context.report({
	node: jsdocNode,
	message: "Missing JSDoc @{{returns}} for function.",
	data: {
	returns: prefer.returns || "returns"
	}
	});
	}
	}

[Standard8]

@rachx now I re-read the docs again(!), I think having returns optional in the requireReturn:false case makes sense.

Updating that section seems to make sense as well. Do you want to do a PR for that, or I could do one tomorrow?

[rachx]

@Standard8 You can make the PR 👍