diff --git a/src/operator/finally.ts b/src/operator/finally.ts index a640f4f490..8f7cd42097 100644 --- a/src/operator/finally.ts +++ b/src/operator/finally.ts @@ -4,10 +4,72 @@ import { finalize } from '../operators/finalize'; /** * Returns an Observable that mirrors the source Observable, but will call a specified function when - * the source terminates on complete or error. - * @param {function} callback Function to be called when source terminates. + * the source terminates on complete, error or unsubscribe. + * + * Ensure a given function will be called when a stream ends, no matter why it ended. + * + * `finally` method accepts as a single parameter a function. This function does not accept any parameters and + * should not return anything. It will be called whenever source Observable completes, errors or is unsubscribed, + * which makes it good candidate to perform any necessary clean up or side effects when Observable terminates, + * no matter how or why it terminated. + * + * Observable returned by `finally` will simply mirror source Observable - each time it is subscribed, source + * Observable will be subscribed underneath. + * + * Note that behavior of `finally` will be repeated per every subscription, so if resulting Observable has + * many subscribers, function passed to `finally` might be potentially called multiple times. + * + * Remember also that `finally` differs quite a lot from passing complete or error handler to {@link subscribe}. It will + * return an Observable which can be further chained, while `subscribe` returns Subscription, basically ending Observable + * chain. Function passed to `finally` will be called also when consumer of resulting Observable unsubscribes from it, + * while handlers passed to `subscribe` will not (even complete handler). But most importantly, `finally` does not start + * an execution of source Observable, like `subscribe` does, allowing you to set up all necessary hooks before + * passing Observable further, even without specific knowledge how or when it will be used. + * + * + * @example