Consider jsdoc/require-throws

[edg2s]

gajus/eslint-plugin-jsdoc#574

[jdforrester]

Generally I'd say yes, but I've seen some colleagues say that "@throws" should only happen when you expect the exception (e.g. you ask for the contents of the file and it doesn't exist), rather than runtime issues (like you ask for the file and the OS is out of memory). Is that something we care about?

[edg2s]

runtime issues

Would those not be throws that happen deeper in the stack? Surely anything that is explicitly thrown by a method (which is all this will detect) should be documented?

[jdforrester]

It was just the most obvious example that came to mind. Can give some real-world ones, but as I'm not the one pushing for this view (just reporting it), it'd be stronger if those who were did.

[edg2s]

There are certainly throws that are never expected to happen in normal operation, but I still think it's useful for users of any method to know if it might throw. Obviously if the method itself doesn't catch all the possible exceptions of the calls it makes that those would be missed.