Closed ehoogeveen-medweb closed 11 months ago
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.
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).
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.
:tada: This issue has been resolved in version 46.8.0 :tada:
The release is available on:
Your semantic-release bot :package::rocket:
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 overforceRequireReturn
orforceReturnsWithAsync
.Alternatives considered
I guess we could use
@internal
to avoid requiring@returns
via theexemptedBy
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.