Document functions that throw or improve with Result type

[jsjoeio]

Prior Art

It's really a shame TypeScript has no support for throwing.

I gave this a thumbs up: microsoft/TypeScript#13219

Thoughts on (I'm thinking we could do this later since we have a lot of throw around) using a sort of DocBlock syntax with @throws? Similar to the example in this issue: microsoft/TypeScript#43528

We could also consider (at a later date, not in this PR) not using throw at all in our codebase and always returning something like Rust's Result.

Context: #3760 (comment)

Solution:

• either document functions with @throws like this example
• create a new ReturnType like Result in Rust
• upvote this issue

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no activity occurs in the next 5 days.