$q's finally documentation is not consistent with implementation

[shahata]

The docs say that finally "allows you to observe either the fulfillment or rejection of a promise, but to do so without modifying the final value".

However, the truth is that if the finally callback throws an exception or returns a promise that later gets rejected, the original promise will be rejected with that exception/reason.

The question is whether we should fix the doc or change the implementation in order match the semantics of Q's finally (which will obviously be a breaking change)...

[shahata]

This behavior exists since finally was added in #2424. I couldn't find any reason for the inconsistency.

[jeffbcross]

Are there compelling use cases that would justify a breaking change? I'd prefer to just update the docs.

[shahata]

The only reason to change it is that it is not consistent with Q and is pretty confusing (Q's implementation makes much more sense imo). I agree it is probably not worth the breaking change though.

[gkalpak]

I don't what the case was in 2014, but Q does the same things now. In our docs we link to the Q API docs for more info, where it is stated that:

[...]
finally returns a promise, which will become resolved with the same fulfillment value or rejection reason as promise. However, if callback returns a promise, the resolution of the returned promise will be delayed until the promise returned from callback is finished. Furthermore, if the returned promise rejects, that rejection will be passed down the chain instead of the previous result.

Afaict, this can be closed. (Feel free to reopen or comment below in case I missed something.)