Add rule for custom @rejects tag

[brettz9]

Motivation

@throws might not really be appropriate for documenting Promise rejections since async functions reject rather than "throw" and because non-async functions may throw and/or reject.

Current behavior

There is no means to enforce that a detectably rejecting Promise has rejection documentation.

Desired behavior

Although there may technically be a throw within an async function that rejects in this manner, but documentation really merits, I think, distinct syntax to suggest instead a Promise rejection error type (also for cases where a rejection occurs through other means besides throw, e.g., Promise.reject or returning a Promise that rejects).

Alternatives considered

Before #722, require-throws had required @throws even for its throw rejections, but no longer does so, and there is no other way to be alerted that a rejection requires documentation.

While it would be nice to use a standard tag, jsdoc has had an open issue for 8 years: jsdoc/jsdoc#509 .

TypeScript has an open issue to allow a non-"any" type to be supplied for the rejection type, potentially allowing for the likes of Promise<ResolveType,RejectionType>, but this has not been approved and such suggestions were previously, um, rejected. There is a popular request from 4 years ago to add a throws ability, but this would only work with TypeScript in that it proposes a new syntax.

---

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