[jsdoc/require-returns] Allow specific contexts to have `forceRequireReturn`

[neurolag]

Motivation

Especially when writing code in TypeScript, there are certain use-cases (when writing abstract methods or interfaces) where you don't have a method- or function-body and therefore want to have forceRequireReturn turned on.

However, you mostly don't want to have forceRequireReturn turned on for all contexts as you might not want to have it turned on for functions without returns in it.

Current behavior

forceRequireReturn can only be set to a boolean allowing the user to force returns for all contexts or not requiring it at all.

Desired behavior

I'd like to be able to provide a string-array as forceRequireReturn-option for specifying the contexts which are required to have a @returns-tag:

{
    "jsdoc/require-returns": [
        "error",
        {
            "forceRequireReturns": [
                "TSEmptyBodyFunctionExpression:not([returnType.typeAnnotation.type='TSVoidKeyword']):not([returnType.typeAnnotation.typeName.name='Promise'][returnType.typeAnnotation.typeParameters.params.0.type='TSVoidKeyword'])",
                "TSMethodSignature:not([returnType.typeAnnotation.type='TSVoidKeyword']):not([returnType.typeAnnotation.typeName.name='Promise'][returnType.typeAnnotation.typeParameters.params.0.type='TSVoidKeyword'])"
            ]
        }
    ]
}

Alternatives considered

Allow passing a boolean-array containing a value indicating whether a @returns-tag is enforced for the corresponding context:

{
    "jsdoc/require-returns": [
        "error",
        {
            "contexts": [
                "FunctionDeclaration"
                "TSEmptyBodyFunctionExpression"
            ],
            "forceRequireReturn": [
                false,
                true
            ]
        }
    ]
}

Or allow passing a context and a, optionally, a boolean indicating whether the specified context forces @returns-tags:

{
    "json/require-returns": [
        "error",
        {
            "contexts": [
                "FunctionDeclaration",
                ["TSEmptyBodyFunctionExpression", true]
            ]
        }
    ]
}

---

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

[brettz9]

We already have a kind of pattern established for context objects, so I think that might be the route to go:

{
    "json/require-returns": [
        "error",
        {
            "contexts": [
                "FunctionDeclaration",
                {context: "TSEmptyBodyFunctionExpression", forceRequireReturns: true}
            ]
        }
    ]
}

This approach would also have the benefits of being more immediately readable and allowing expansion to any other context-specific config.

[github-actions[bot]]

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

The release is available on:

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

Your semantic-release bot :package::rocket: