Potentially incorrect documentation example for no-return-await

[cyberwombat]

According to the docs: https://github.com/eslint/eslint/blob/master/docs/rules/no-return-await.md the following are not essentially equivalent.

Example of invalid usage:

async function foo() {
    return await bar();
}

Example of valid usage:

async function foo() {
    const x = await bar();
    return x;
}

That makes no sense. Neither is proper usage. Is this a documentation bug or am I misunderstanding why it's there (stack trace is all I can think of)

[mdjermanovic]

Hi @cyberwombat, thanks for the issue!

Examples of correct code do not aim to imply that it is a "valid usage". It's just a lint-free code for the rule.

The const example is correctly in "Examples of correct code for this rule" because this rule checks only return statements, so it doesn't report that code.

Maybe we should add a comment above this example, to avoid confusion?

[cyberwombat]

@mdjermanovic I see. Yes I think a comment would be in order. I posted this as the result of a lengthy reddit discussion where we are wondering why eslint is saying they are not essentially the same. I'd recommend removing it from the "valid" section and adding it below with a mention that while it's incorrect eslint will not check it. What do you think?

[mdjermanovic]

I made a docs PR #13657.

It seemed a bit complicated to separate this example. We can't formulate that it's "incorrect" in general because the document also lists some use cases in favor of return await (in the opening section and in the When Not To Use It section). It also isn't incorrect by this rule (it does look incorrect if we follow the logic of the rule, but the rule still doesn't report it), so it seemed best to just leave the example where it was, with an added comment.

[cyberwombat]

Great. sounds good! I'll let you close this - dunno if it needs to stay open for the PR.