Skip to content

Commit

Permalink
fix(docs): fix code examples (#3784)
Browse files Browse the repository at this point in the history
  • Loading branch information
niklas-wortmann authored and benlesh committed Jun 4, 2018
1 parent 7b19e12 commit a95441b
Show file tree
Hide file tree
Showing 95 changed files with 534 additions and 194 deletions.
21 changes: 13 additions & 8 deletions src/internal/Observable.ts
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,9 @@ export class Observable<T> implements Subscribable<T> {
* by default emits all its values synchronously. Always check documentation for how given Observable
* will behave when subscribed and if its default behavior can be modified with a {@link Scheduler}.
*
* @example <caption>Subscribe with an Observer</caption>
* ## Example
* ### Subscribe with an Observer
* ```javascript
* const sumObserver = {
* sum: 0,
* next(value) {
Expand All @@ -132,9 +134,10 @@ export class Observable<T> implements Subscribable<T> {
* // "Adding: 2"
* // "Adding: 3"
* // "Sum equals: 6"
* ```
*
*
* @example <caption>Subscribe with functions</caption>
* ### Subscribe with functions
* ```javascript
* let sum = 0;
*
* Rx.Observable.of(1, 2, 3)
Expand All @@ -154,9 +157,10 @@ export class Observable<T> implements Subscribable<T> {
* // "Adding: 2"
* // "Adding: 3"
* // "Sum equals: 6"
* ```
*
*
* @example <caption>Cancel a subscription</caption>
* ### Cancel a subscription
* ```javascript
* const subscription = Rx.Observable.interval(1000).subscribe(
* num => console.log(num),
* undefined,
Expand All @@ -173,7 +177,7 @@ export class Observable<T> implements Subscribable<T> {
* // 0 after 1s
* // 1 after 2s
* // "unsubscribed!" after 2.5s
*
* ```
*
* @param {Observer|Function} observerOrNext (optional) Either an observer with methods to be called,
* or the first of three possible handlers, which is the handler for each value emitted from the subscribed
Expand Down Expand Up @@ -301,8 +305,8 @@ export class Observable<T> implements Subscribable<T> {
* @return {Observable} the Observable result of all of the operators having
* been called in the order they were passed in.
*
* @example
*
* ### Example
* ```javascript
* import { map, filter, scan } from 'rxjs/operators';
*
* Rx.Observable.interval(1000)
Expand All @@ -312,6 +316,7 @@ export class Observable<T> implements Subscribable<T> {
* scan((acc, x) => acc + x)
* )
* .subscribe(x => console.log(x))
* ```
*/
pipe<R>(...operations: OperatorFunction<T, R>[]): Observable<R> {
if (operations.length === 0) {
Expand Down
21 changes: 13 additions & 8 deletions src/internal/observable/bindCallback.ts
Original file line number Diff line number Diff line change
Expand Up @@ -107,15 +107,18 @@ export function bindCallback(callbackFunc: Function, scheduler?: SchedulerLike):
* `bindCallback` will treat such functions the same as any other and error parameters
* (whether passed or not) will always be interpreted as regular callback argument.
*
* ## Examples
*
* @example <caption>Convert jQuery's getJSON to an Observable API</caption>
* ### Convert jQuery's getJSON to an Observable API
* ```javascript
* // Suppose we have jQuery.getJSON('/my/url', callback)
* var getJSONAsObservable = bindCallback(jQuery.getJSON);
* var result = getJSONAsObservable('/my/url');
* result.subscribe(x => console.log(x), e => console.error(e));
* ```
*
*
* @example <caption>Receive an array of arguments passed to a callback</caption>
* ### Receive an array of arguments passed to a callback
* ```javascript
* someFunction((a, b, c) => {
* console.log(a); // 5
* console.log(b); // 'some string'
Expand All @@ -126,9 +129,10 @@ export function bindCallback(callbackFunc: Function, scheduler?: SchedulerLike):
* boundSomeFunction().subscribe(values => {
* console.log(values) // [5, 'some string', {someProperty: 'someValue'}]
* });
* ```
*
*
* @example <caption>Compare behaviour with and without async Scheduler</caption>
* ### Compare behaviour with and without async Scheduler
* ```javascript
* function iCallMyCallbackSynchronously(cb) {
* cb();
* }
Expand All @@ -144,13 +148,14 @@ export function bindCallback(callbackFunc: Function, scheduler?: SchedulerLike):
* // I was sync!
* // This happened...
* // I was async!
* ```
*
*
* @example <caption>Use bindCallback on an object method</caption>
* ### Use bindCallback on an object method
* ```javascript
* const boundMethod = bindCallback(someObject.methodWithCallback);
* boundMethod.call(someObject) // make sure methodWithCallback has access to someObject
* .subscribe(subscriber);
*
* ```
*
* @see {@link bindNodeCallback}
* @see {@link from}
Expand Down
16 changes: 10 additions & 6 deletions src/internal/observable/bindNodeCallback.ts
Original file line number Diff line number Diff line change
Expand Up @@ -105,15 +105,17 @@ export function bindNodeCallback(callbackFunc: Function, scheduler?: SchedulerLi
* Note that even if error parameter is technically present in callback, but its value
* is falsy, it still won't appear in array emitted by Observable.
*
*
* @example <caption>Read a file from the filesystem and get the data as an Observable</caption>
* ## Examples
* ### Read a file from the filesystem and get the data as an Observable
* ```javascript
* import * as fs from 'fs';
* var readFileAsObservable = bindNodeCallback(fs.readFile);
* var result = readFileAsObservable('./roadNames.txt', 'utf8');
* result.subscribe(x => console.log(x), e => console.error(e));
* ```
*
*
* @example <caption>Use on function calling callback with multiple arguments</caption>
* ### Use on function calling callback with multiple arguments
* ```javascript
* someFunction((err, a, b) => {
* console.log(err); // null
* console.log(a); // 5
Expand All @@ -124,8 +126,10 @@ export function bindNodeCallback(callbackFunc: Function, scheduler?: SchedulerLi
* .subscribe(value => {
* console.log(value); // [5, "some string"]
* });
* ```
*
* @example <caption>Use on function calling callback in regular style</caption>
* ### Use on function calling callback in regular style
* ```javascript
* someFunction(a => {
* console.log(a); // 5
* });
Expand All @@ -135,7 +139,7 @@ export function bindNodeCallback(callbackFunc: Function, scheduler?: SchedulerLi
* value => {} // never gets called
* err => console.log(err) // 5
* );
*
* ```
*
* @see {@link bindCallback}
* @see {@link from}
Expand Down
17 changes: 10 additions & 7 deletions src/internal/observable/combineLatest.ts
Original file line number Diff line number Diff line change
Expand Up @@ -93,8 +93,9 @@ export function combineLatest<R>(...observables: Array<ObservableInput<any> | ((
* of values, but values themselves. That means default `project` can be imagined
* as function that takes all its arguments and puts them into an array.
*
*
* @example <caption>Combine two timer Observables</caption>
* ## Examples
* ### Combine two timer Observables
* ```javascript
* const firstTimer = Rx.Observable.timer(0, 1000); // emit 0, 1, 2... after every second, starting from now
* const secondTimer = Rx.Observable.timer(500, 1000); // emit 0, 1, 2... after every second, starting 0,5s from now
* const combinedTimers = Rx.Observable.combineLatest(firstTimer, secondTimer);
Expand All @@ -104,9 +105,10 @@ export function combineLatest<R>(...observables: Array<ObservableInput<any> | ((
* // [1, 0] after 1s
* // [1, 1] after 1.5s
* // [2, 1] after 2s
* ```
*
*
* @example <caption>Combine an array of Observables</caption>
* ### Combine an array of Observables
* ```javascript
* const observables = [1, 5, 10].map(
* n => Rx.Observable.of(n).delay(n * 1000).startWith(0) // emit 0 and then emit n after n seconds
* );
Expand All @@ -117,9 +119,10 @@ export function combineLatest<R>(...observables: Array<ObservableInput<any> | ((
* // [1, 0, 0] after 1s
* // [1, 5, 0] after 5s
* // [1, 5, 10] after 10s
* ```
*
*
* @example <caption>Use project function to dynamically calculate the Body-Mass Index</caption>
* ### Use project function to dynamically calculate the Body-Mass Index
* ```javascript
* var weight = Rx.Observable.of(70, 72, 76, 79, 75);
* var height = Rx.Observable.of(1.76, 1.77, 1.78);
* var bmi = Rx.Observable.combineLatest(weight, height, (w, h) => w / (h * h));
Expand All @@ -129,7 +132,7 @@ export function combineLatest<R>(...observables: Array<ObservableInput<any> | ((
* // BMI is 24.212293388429753
* // BMI is 23.93948099205209
* // BMI is 23.671253629592222
*
* ```
*
* @see {@link combineAll}
* @see {@link merge}
Expand Down
14 changes: 9 additions & 5 deletions src/internal/observable/concat.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,17 +52,19 @@ export function concat<T, R>(...observables: (ObservableInput<any> | SchedulerLi
* as many times as you like. If passing the same Observable to `concat` 1000 times becomes tedious,
* you can always use {@link repeat}.
*
* @example <caption>Concatenate a timer counting from 0 to 3 with a synchronous sequence from 1 to 10</caption>
* ## Examples
* ### Concatenate a timer counting from 0 to 3 with a synchronous sequence from 1 to 10
* ```javascript
* var timer = Rx.Observable.interval(1000).take(4);
* var sequence = Rx.Observable.range(1, 10);
* var result = Rx.Observable.concat(timer, sequence);
* result.subscribe(x => console.log(x));
*
* // results in:
* // 0 -1000ms-> 1 -1000ms-> 2 -1000ms-> 3 -immediate-> 1 ... 10
* ```
*
*
* @example <caption>Concatenate an array of 3 Observables</caption>
* ### Concatenate an array of 3 Observables
* var timer1 = Rx.Observable.interval(1000).take(10);
* var timer2 = Rx.Observable.interval(2000).take(6);
* var timer3 = Rx.Observable.interval(500).take(10);
Expand All @@ -74,9 +76,10 @@ export function concat<T, R>(...observables: (ObservableInput<any> | SchedulerLi
* // -1000ms-> 0 -1000ms-> 1 -1000ms-> ... 9
* // -2000ms-> 0 -2000ms-> 1 -2000ms-> ... 5
* // -500ms-> 0 -500ms-> 1 -500ms-> ... 9
* ```
*
*
* @example <caption>Concatenate the same Observable to repeat it</caption>
* ### Concatenate the same Observable to repeat it
* ```javascript
* const timer = Rx.Observable.interval(1000).take(2);
*
* Rx.Observable.concat(timer, timer) // concating the same Observable!
Expand All @@ -92,6 +95,7 @@ export function concat<T, R>(...observables: (ObservableInput<any> | SchedulerLi
* // 0 after 3s
* // 1 after 4s
* // "...and it is done!" also after 4s
* ```
*
* @see {@link concatAll}
* @see {@link concatMap}
Expand Down
5 changes: 4 additions & 1 deletion src/internal/observable/defer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,9 @@ import { empty } from './empty';
* same Observable, in fact each subscriber gets its own individual
* Observable.
*
* @example <caption>Subscribe to either an Observable of clicks or an Observable of interval, at random</caption>
* ## Example
* ### Subscribe to either an Observable of clicks or an Observable of interval, at random
* ```javascript
* var clicksOrInterval = Rx.Observable.defer(function () {
* if (Math.random() > 0.5) {
* return Rx.Observable.fromEvent(document, 'click');
Expand All @@ -36,6 +38,7 @@ import { empty } from './empty';
* // for clicks anywhere on the "document"; when document is clicked it
* // will log a MouseEvent object to the console. If the result is less
* // than 0.5 it will emit ascending numbers, one every second(1000ms).
* ```
*
* @see {@link create}
*
Expand Down
4 changes: 3 additions & 1 deletion src/internal/observable/dom/AjaxObservable.ts
Original file line number Diff line number Diff line change
Expand Up @@ -110,9 +110,11 @@ export class AjaxObservable<T> extends Observable<T> {
* Creates an observable for an Ajax request with either a request object with
* url, headers, etc or a string for a URL.
*
* @example
* ## Example
* ```javascript
* source = Rx.Observable.ajax('/products');
* source = Rx.Observable.ajax({ url: 'products', method: 'GET' });
* ```
*
* @param {string|Object} request Can be one of the following:
* A string of the URL to make the Ajax call.
Expand Down
11 changes: 7 additions & 4 deletions src/internal/observable/dom/webSocket.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,9 @@ import { WebSocketSubject, WebSocketSubjectConfig } from './WebSocketSubject';
/**
* Wrapper around the w3c-compatible WebSocket object provided by the browser.
*
* @example <caption>Wraps browser WebSocket</caption>
*
* ## Examples
* ### Wrapping browser WebSocket
* ```javascript
* import { webSocket } from 'rxjs/webSocket';
*
* let socket$ = webSocket('ws://localhost:8081');
Expand All @@ -16,9 +17,10 @@ import { WebSocketSubject, WebSocketSubjectConfig } from './WebSocketSubject';
* );
*
* socket$.next(JSON.stringify({ op: 'hello' }));
* ```
*
* @example <caption>Wraps WebSocket from nodejs-webSocket (using node.js)</caption>
*
* ### Wraps nodejs-webSocket</caption>
* ```javascript
* import { webSocket } from 'rxjs/webSocket';
* import { w3cwebSocket } from 'webSocket';
*
Expand All @@ -34,6 +36,7 @@ import { WebSocketSubject, WebSocketSubjectConfig } from './WebSocketSubject';
* );
*
* socket$.next(JSON.stringify({ op: 'hello' }));
* ```
*
* @param {string | WebSocketSubjectConfig} urlConfigOrSource the source of the webSocket as an url or a structure defining the webSocket object
* @return {WebSocketSubject}
Expand Down
9 changes: 7 additions & 2 deletions src/internal/observable/empty.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,15 @@ export const EMPTY = new Observable<never>(subscriber => subscriber.complete());
* emits the complete notification. It can be used for composing with other
* Observables, such as in a {@link mergeMap}.
*
* @example <caption>Emit the number 7, then complete.</caption>
* ## Examples
* ### Emit the number 7, then complete
* ```javascript
* var result = Rx.Observable.empty().startWith(7);
* result.subscribe(x => console.log(x));
* ```
*
* @example <caption>Map and flatten only odd numbers to the sequence 'a', 'b', 'c'</caption>
* ### Map and flatten only odd numbers to the sequence 'a', 'b', 'c'
* ```javascript
* var interval = Rx.Observable.interval(1000);
* var result = interval.mergeMap(x =>
* x % 2 === 1 ? Rx.Observable.of('a', 'b', 'c') : Rx.Observable.empty()
Expand All @@ -36,6 +40,7 @@ export const EMPTY = new Observable<never>(subscriber => subscriber.complete());
* // x will occur every 1000ms
* // if x % 2 is equal to 1 print abc
* // if x % 2 is not equal to 1 nothing will be output
* ```
*
* @see {@link create}
* @see {@link never}
Expand Down
15 changes: 10 additions & 5 deletions src/internal/observable/forkJoin.ts
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,9 @@ export function forkJoin<T>(...sources: ObservableInput<T>[]): Observable<T[]>;
* all its arguments and puts them into an array. Note that project function will be called only
* when output Observable is supposed to emit a result.
*
* @example <caption>Use forkJoin with operator emitting immediately</caption>
* ## Examples
* ### Use forkJoin with operator emitting immediately
* ```javascript
* import { forkJoin, of } from 'rxjs';
*
* const observable = forkJoin(
Expand All @@ -83,9 +85,10 @@ export function forkJoin<T>(...sources: ObservableInput<T>[]): Observable<T[]>;
* // Logs:
* // [4, 8]
* // "This is how it ends!"
* ```
*
*
* @example <caption>Use forkJoin with operator emitting after some time</caption>
* ### Use forkJoin with operator emitting after some time
* ```javascript
* import { forkJoin, interval } from 'rxjs';
* import { take } from 'rxjs/operators';
*
Expand All @@ -102,9 +105,10 @@ export function forkJoin<T>(...sources: ObservableInput<T>[]): Observable<T[]>;
* // Logs:
* // [2, 3] after 3 seconds
* // "This is how it ends!" immediately after
* ```
*
*
* @example <caption>Use forkJoin with project function</caption>
* ### Use forkJoin with project function
* ```javascript
* import { jorkJoin, interval } from 'rxjs';
* import { take } from 'rxjs/operators';
*
Expand All @@ -122,6 +126,7 @@ export function forkJoin<T>(...sources: ObservableInput<T>[]): Observable<T[]>;
* // Logs:
* // 5 after 3 seconds
* // "This is how it ends!" immediately after
* ```
*
* @see {@link combineLatest}
* @see {@link zip}
Expand Down
Loading

0 comments on commit a95441b

Please sign in to comment.