[require-returns] Add an option to require a `returns`-tag if TS type annotation is other than void/Promise<void>

[neurolag]

In typescript you have the option to specify the return-type of a function:

// Function
function test(): string { }
// Arrow-Function
let test = (): string => { };
// FunctionType
let test: () => string;

// Abstract method
class Test {
  abstract Test(): string;
}

Do you guys think its smart to add an option to also require a @returns-parameter if a return-type other than none, void or Promise<void> is specified?
Or do you think this would go too far?

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[brettz9]

If you mean to check the actual return value to see if @returns is needed, there is already require-returns. But I guess you mean that if using TypeScript return types, @returns should be required? Some users may actually want to disable the rule in such cases as it might be seen as partially redundant, though I can see some would want one if one is requiring a description.

I'd be ok with such a feature myself or reviewing a PR, though as I'm not working with TS, that would not be on my priority list.

[brettz9]

This can be achieved now with the jsdoc/no-restricted-syntax rule. See #976 (specifically https://github.com/gajus/eslint-plugin-jsdoc/pull/976/files#diff-545a867764ce23fa04a08e7f0207aacd009b8343965ede162d8f09d9b718a844 ) for the options you can supply to detect and report on type annotations with non-void return types missing the @returns or @returns with a description.

[brettz9]

For example:

/**
 * @returns
 */
let test: () => string;

will err with the following options due to not having a description line within the @returns:

'jsdoc/no-restricted-syntax': [
  'error',
  {
    contexts: [
      {
        comment: 'JsdocBlock:not(*:has(JsdocTag[tag=/returns/]:has(JsdocDescriptionLine)))',
        context: 'VariableDeclaration:has(*[typeAnnotation.typeAnnotation.type=/TSFunctionType/][typeAnnotation.typeAnnotation.returnType.typeAnnotation.type!=/TSVoidKeyword|TSUndefinedKeyword/])',
        message: 'FunctionType\'s with non-void return types must have a @returns tag with a description',
      },
    ],
  },
],

[github-actions]

🎉 This issue has been resolved in version 39.8.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀