From 83ebe90eed9ba2c100d5d0e85a43498075dcdf1d Mon Sep 17 00:00:00 2001 From: Mateusz Podlasin Date: Wed, 3 May 2017 02:08:37 +0200 Subject: [PATCH] docs(observeOn): create the documentation (#2541) Create documentation for the operator, describing what it can be used for, what parameters accepts and returns. Add example of typical usage and compare the operator with delay operator. --- src/operator/observeOn.ts | 45 +++++++++++++++++++++++++++++++++++---- 1 file changed, 41 insertions(+), 4 deletions(-) diff --git a/src/operator/observeOn.ts b/src/operator/observeOn.ts index 0b437bd639..ecbacd9899 100644 --- a/src/operator/observeOn.ts +++ b/src/operator/observeOn.ts @@ -8,11 +8,48 @@ import { TeardownLogic } from '../Subscription'; import { Action } from '../scheduler/Action'; /** - * @see {@link Notification} * - * @param scheduler - * @param delay - * @return {Observable|WebSocketSubject|Observable} + * Re-emits all notifications from source Observable with specified scheduler. + * + * Ensure a specific scheduler is used, from outside of an Observable. + * + * `observeOn` is an operator that accepts a scheduler as a first parameter, which will be used to reschedule + * notifications emitted by the source Observable. It might be useful, if you do not have control over + * internal scheduler of a given Observable, but want to control when its values are emitted nevertheless. + * + * Returned Observable emits the same notifications (nexted values, complete and error events) as the source Observable, + * but rescheduled with provided scheduler. Note that this doesn't mean that source Observables internal + * scheduler will be replaced in any way. Original scheduler still will be used, but when the source Observable emits + * notification, it will be immediately scheduled again - this time with scheduler passed to `observeOn`. + * An anti-pattern would be calling `observeOn` on Observable that emits lots of values synchronously, to split + * that emissions into asynchronous chunks. For this to happen, scheduler would have to be passed into the source + * Observable directly (usually into the operator that creates it). `observeOn` simply delays notifications a + * little bit more, to ensure that they are emitted at expected moments. + * + * As a matter of fact, `observeOn` accepts second parameter, which specifies in milliseconds with what delay notifications + * will be emitted. The main difference between {@link delay} operator and `observeOn` is that `observeOn` + * will delay all notifications - including error notifications - while `delay` will pass through error + * from source Observable immediately when it is emitted. In general it is highly recommended to use `delay` operator + * for any kind of delaying of values in the stream, while using `observeOn` to specify which scheduler should be used + * for notification emissions in general. + * + * @example Ensure values in subscribe are called just before browser repaint. + * const intervals = Rx.Observable.interval(10); // Intervals are scheduled + * // with async scheduler by default... + * + * intervals + * .observeOn(Rx.Scheduler.animationFrame) // ...but we will observe on animationFrame + * .subscribe(val => { // scheduler to ensure smooth animation. + * someDiv.style.height = val + 'px'; + * }); + * + * @see {@link delay} + * + * @param {IScheduler} scheduler Scheduler that will be used to reschedule notifications from source Observable. + * @param {number} [delay] Number of milliseconds that states with what delay every notification should be rescheduled. + * @return {Observable} Observable that emits the same notifications as the source Observable, + * but with provided scheduler. + * * @method observeOn * @owner Observable */