Eslint-plugin-jsdoc: "require-returns" requires useless return statements for return type "undefined"

[lll000111]

Subject says it. If the return type is undefined I don't need a return statement in the code.

This plugin should concern itself with JSDoc — not with the code style! The return type when there is no return statement is undefined, so describing such a function as having @returns {undefined} is 100% correct. I should not get

Present JSDoc @returns declaration but not available return expression in function  jsdoc/require-returns

[gajus]

PR is welcome.

[lll000111]

Sure, always. And so are big reports, and here is one.

[ibbignerd]

According to ESLint, @returns {void} should be valid.

According to Google Closure Compiler, omitting it completely or @returns {undefined] should be valid. The following should all be tests that satisfy these requirements.

valid: [
    { // pass
      code: `
          /**
           * @returns {Object}
           */
          function quux () {

            return {a: foo};
          }
      `
    },
    { // fail
      code: `
          /**
           * @returns {Object}
           */
          const quux = () => ({a: foo});
      `
    },
    { // pass
      code: `
          /**
           * @returns {Object}
           */
          const quux = () => {
            return {a: foo}
          };
      `
    },
    { // fail
      code: `
          /**
           * @returns {void}
           */
          function quux () {
          }
      `
    },
    { // fail
      code: `
          /**
           * @returns {void}
           */
          const quux = () => {

          }
      `
    },
    { // fail
      code: `
          /**
           * @returns {undefined}
           */
          function quux () {
          }
      `
    },
    { // fail
      code: `
          /**
           * @returns {undefined}
           */
          const quux = () => {

          }
      `
    },
    { // pass
      code: `
          /**
           *
           */
          function quux () {
          }
      `
    },
    { // pass
      code: `
          /**
           *
           */
          const quux = () => {

          }
      `
    }
  ]

Pass/Fail comments are as of v3.15.1.

[ChrisHSandN]

It's no PR, but might be helpful. This is the change I made to work around this bug and get my code validating:

https://github.com/gajus/eslint-plugin-jsdoc/blob/master/src/rules/requireReturns.js

// replace
if (JSON.stringify(jsdocTags) !== '[]' && sourcecode.indexOf('return') < 1) {
// with
if (JSON.stringify(jsdocTags) !== '[]' && jsdocTags.findIndex(v => ['undefined', 'void'].indexOf(v.type) !== -1) === -1 && sourcecode.indexOf('return') < 1) {

Lots of the core ESLint rules seem to have a configurable options object to enable/disable parts of a rule, As this rule has 2 report() cases maybe it would be logical to allow them to be enabled separately?

[gajus]

Lots of the core ESLint rules seem to have a configurable options object to enable/disable parts of a rule, As this rule has 2 report() cases maybe it would be logical to allow them to be enabled separately?

Makes sense.

[ptkdev]

Hi,
Sorry for this bug. I fix this in a pull request.
I use @ChrisHSandN patch (thanks, imho is ok) and split this rule in two rules.

[brettz9]

I would hope that this behavior could made optional because I personally always want returns documented so as to flag there has been no omission in consideration of return values for documentation.

[gajus]

:tada: This issue has been resolved in version 4.8.2 :tada:

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot :package::rocket: