require-returns only on exported functions

[ehoogeveen-medweb]

Motivation

We primarily use jsdoc comments to document our types for on-hover information in VSCode. Return types can often be inferred by typescript from the function body (even for javascript code), making @returns annotations redundant (aside from descriptions, which I also consider optional).

Exported functions are an exception: I believe the API surface should be fully documented, and inference across module boundaries is potentially slower as well.

Current behavior

I don't think there is currently a way to automatically require @returns annotations only on exported functions.

Desired behavior

I would like to see an option, e.g. onlyExported, that makes the rule only check exported symbols. I think this option should take precedence over forceRequireReturn or forceReturnsWithAsync.

Alternatives considered

I guess we could use @internal to avoid requiring @returns via the exemptedBy option, but we don't use that currently. I'd like to encourage use of jsdoc comments in our codebase with minimal barrier to entry.

[ehoogeveen-medweb]

This request applies to require-returns-type as well for the same reason: If you are documenting a return value, the type should only be required for exported symbols.

[brettz9]

I've submitted #1156 for this.

I'm not convinced we really need a require-returns-type equivalent as I think most projects enabling the rule would want a @returns without a type to be reported regardless of its context).

[ehoogeveen-medweb]

Thanks! I'm sure we can live with adding types for require-returns-type if we feel the need to document a return value for an internal function.

[github-actions]

🎉 This issue has been resolved in version 46.8.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀