Skip to content

Commit a95441b

Browse files
niklas-wortmannbenlesh
niklas-wortmann
authored and
benlesh
committed
fix(docs): fix code examples (#3784)
1 parent 7b19e12 commit a95441b

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

95 files changed

+534
-194
lines changed

‎src/internal/Observable.ts‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,9 @@ export class Observable<T> implements Subscribable<T> {
110110
* by default emits all its values synchronously. Always check documentation for how given Observable
111111
* will behave when subscribed and if its default behavior can be modified with a {@link Scheduler}.
112112
*
113-
* @example <caption>Subscribe with an Observer</caption>
113+
* ## Example
114+
* ### Subscribe with an Observer
115+
* ```javascript
114116
* const sumObserver = {
115117
* sum: 0,
116118
* next(value) {
@@ -132,9 +134,10 @@ export class Observable<T> implements Subscribable<T> {
132134
* // "Adding: 2"
133135
* // "Adding: 3"
134136
* // "Sum equals: 6"
137+
* ```
135138
*
136-
*
137-
* @example <caption>Subscribe with functions</caption>
139+
* ### Subscribe with functions
140+
* ```javascript
138141
* let sum = 0;
139142
*
140143
* Rx.Observable.of(1, 2, 3)
@@ -154,9 +157,10 @@ export class Observable<T> implements Subscribable<T> {
154157
* // "Adding: 2"
155158
* // "Adding: 3"
156159
* // "Sum equals: 6"
160+
* ```
157161
*
158-
*
159-
* @example <caption>Cancel a subscription</caption>
162+
* ### Cancel a subscription
163+
* ```javascript
160164
* const subscription = Rx.Observable.interval(1000).subscribe(
161165
* num => console.log(num),
162166
* undefined,
@@ -173,7 +177,7 @@ export class Observable<T> implements Subscribable<T> {
173177
* // 0 after 1s
174178
* // 1 after 2s
175179
* // "unsubscribed!" after 2.5s
176-
*
180+
* ```
177181
*
178182
* @param {Observer|Function} observerOrNext (optional) Either an observer with methods to be called,
179183
* or the first of three possible handlers, which is the handler for each value emitted from the subscribed
@@ -301,8 +305,8 @@ export class Observable<T> implements Subscribable<T> {
301305
* @return {Observable} the Observable result of all of the operators having
302306
* been called in the order they were passed in.
303307
*
304-
* @example
305-
*
308+
* ### Example
309+
* ```javascript
306310
* import { map, filter, scan } from 'rxjs/operators';
307311
*
308312
* Rx.Observable.interval(1000)
@@ -312,6 +316,7 @@ export class Observable<T> implements Subscribable<T> {
312316
* scan((acc, x) => acc + x)
313317
* )
314318
* .subscribe(x => console.log(x))
319+
* ```
315320
*/
316321
pipe<R>(...operations: OperatorFunction<T, R>[]): Observable<R> {
317322
if (operations.length === 0) {

‎src/internal/observable/bindCallback.ts‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -107,15 +107,18 @@ export function bindCallback(callbackFunc: Function, scheduler?: SchedulerLike):
107107
* `bindCallback` will treat such functions the same as any other and error parameters
108108
* (whether passed or not) will always be interpreted as regular callback argument.
109109
*
110+
* ## Examples
110111
*
111-
* @example <caption>Convert jQuery's getJSON to an Observable API</caption>
112+
* ### Convert jQuery's getJSON to an Observable API
113+
* ```javascript
112114
* // Suppose we have jQuery.getJSON('/my/url', callback)
113115
* var getJSONAsObservable = bindCallback(jQuery.getJSON);
114116
* var result = getJSONAsObservable('/my/url');
115117
* result.subscribe(x => console.log(x), e => console.error(e));
118+
* ```
116119
*
117-
*
118-
* @example <caption>Receive an array of arguments passed to a callback</caption>
120+
* ### Receive an array of arguments passed to a callback
121+
* ```javascript
119122
* someFunction((a, b, c) => {
120123
* console.log(a); // 5
121124
* console.log(b); // 'some string'
@@ -126,9 +129,10 @@ export function bindCallback(callbackFunc: Function, scheduler?: SchedulerLike):
126129
* boundSomeFunction().subscribe(values => {
127130
* console.log(values) // [5, 'some string', {someProperty: 'someValue'}]
128131
* });
132+
* ```
129133
*
130-
*
131-
* @example <caption>Compare behaviour with and without async Scheduler</caption>
134+
* ### Compare behaviour with and without async Scheduler
135+
* ```javascript
132136
* function iCallMyCallbackSynchronously(cb) {
133137
* cb();
134138
* }
@@ -144,13 +148,14 @@ export function bindCallback(callbackFunc: Function, scheduler?: SchedulerLike):
144148
* // I was sync!
145149
* // This happened...
146150
* // I was async!
151+
* ```
147152
*
148-
*
149-
* @example <caption>Use bindCallback on an object method</caption>
153+
* ### Use bindCallback on an object method
154+
* ```javascript
150155
* const boundMethod = bindCallback(someObject.methodWithCallback);
151156
* boundMethod.call(someObject) // make sure methodWithCallback has access to someObject
152157
* .subscribe(subscriber);
153-
*
158+
* ```
154159
*
155160
* @see {@link bindNodeCallback}
156161
* @see {@link from}

‎src/internal/observable/bindNodeCallback.ts‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -105,15 +105,17 @@ export function bindNodeCallback(callbackFunc: Function, scheduler?: SchedulerLi
105105
* Note that even if error parameter is technically present in callback, but its value
106106
* is falsy, it still won't appear in array emitted by Observable.
107107
*
108-
*
109-
* @example <caption>Read a file from the filesystem and get the data as an Observable</caption>
108+
* ## Examples
109+
* ### Read a file from the filesystem and get the data as an Observable
110+
* ```javascript
110111
* import * as fs from 'fs';
111112
* var readFileAsObservable = bindNodeCallback(fs.readFile);
112113
* var result = readFileAsObservable('./roadNames.txt', 'utf8');
113114
* result.subscribe(x => console.log(x), e => console.error(e));
115+
* ```
114116
*
115-
*
116-
* @example <caption>Use on function calling callback with multiple arguments</caption>
117+
* ### Use on function calling callback with multiple arguments
118+
* ```javascript
117119
* someFunction((err, a, b) => {
118120
* console.log(err); // null
119121
* console.log(a); // 5
@@ -124,8 +126,10 @@ export function bindNodeCallback(callbackFunc: Function, scheduler?: SchedulerLi
124126
* .subscribe(value => {
125127
* console.log(value); // [5, "some string"]
126128
* });
129+
* ```
127130
*
128-
* @example <caption>Use on function calling callback in regular style</caption>
131+
* ### Use on function calling callback in regular style
132+
* ```javascript
129133
* someFunction(a => {
130134
* console.log(a); // 5
131135
* });
@@ -135,7 +139,7 @@ export function bindNodeCallback(callbackFunc: Function, scheduler?: SchedulerLi
135139
* value => {} // never gets called
136140
* err => console.log(err) // 5
137141
* );
138-
*
142+
* ```
139143
*
140144
* @see {@link bindCallback}
141145
* @see {@link from}

‎src/internal/observable/combineLatest.ts‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -93,8 +93,9 @@ export function combineLatest<R>(...observables: Array<ObservableInput<any> | ((
9393
* of values, but values themselves. That means default `project` can be imagined
9494
* as function that takes all its arguments and puts them into an array.
9595
*
96-
*
97-
* @example <caption>Combine two timer Observables</caption>
96+
* ## Examples
97+
* ### Combine two timer Observables
98+
* ```javascript
9899
* const firstTimer = Rx.Observable.timer(0, 1000); // emit 0, 1, 2... after every second, starting from now
99100
* const secondTimer = Rx.Observable.timer(500, 1000); // emit 0, 1, 2... after every second, starting 0,5s from now
100101
* const combinedTimers = Rx.Observable.combineLatest(firstTimer, secondTimer);
@@ -104,9 +105,10 @@ export function combineLatest<R>(...observables: Array<ObservableInput<any> | ((
104105
* // [1, 0] after 1s
105106
* // [1, 1] after 1.5s
106107
* // [2, 1] after 2s
108+
* ```
107109
*
108-
*
109-
* @example <caption>Combine an array of Observables</caption>
110+
* ### Combine an array of Observables
111+
* ```javascript
110112
* const observables = [1, 5, 10].map(
111113
* n => Rx.Observable.of(n).delay(n * 1000).startWith(0) // emit 0 and then emit n after n seconds
112114
* );
@@ -117,9 +119,10 @@ export function combineLatest<R>(...observables: Array<ObservableInput<any> | ((
117119
* // [1, 0, 0] after 1s
118120
* // [1, 5, 0] after 5s
119121
* // [1, 5, 10] after 10s
122+
* ```
120123
*
121-
*
122-
* @example <caption>Use project function to dynamically calculate the Body-Mass Index</caption>
124+
* ### Use project function to dynamically calculate the Body-Mass Index
125+
* ```javascript
123126
* var weight = Rx.Observable.of(70, 72, 76, 79, 75);
124127
* var height = Rx.Observable.of(1.76, 1.77, 1.78);
125128
* var bmi = Rx.Observable.combineLatest(weight, height, (w, h) => w / (h * h));
@@ -129,7 +132,7 @@ export function combineLatest<R>(...observables: Array<ObservableInput<any> | ((
129132
* // BMI is 24.212293388429753
130133
* // BMI is 23.93948099205209
131134
* // BMI is 23.671253629592222
132-
*
135+
* ```
133136
*
134137
* @see {@link combineAll}
135138
* @see {@link merge}

‎src/internal/observable/concat.ts‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -52,17 +52,19 @@ export function concat<T, R>(...observables: (ObservableInput<any> | SchedulerLi
5252
* as many times as you like. If passing the same Observable to `concat` 1000 times becomes tedious,
5353
* you can always use {@link repeat}.
5454
*
55-
* @example <caption>Concatenate a timer counting from 0 to 3 with a synchronous sequence from 1 to 10</caption>
55+
* ## Examples
56+
* ### Concatenate a timer counting from 0 to 3 with a synchronous sequence from 1 to 10
57+
* ```javascript
5658
* var timer = Rx.Observable.interval(1000).take(4);
5759
* var sequence = Rx.Observable.range(1, 10);
5860
* var result = Rx.Observable.concat(timer, sequence);
5961
* result.subscribe(x => console.log(x));
6062
*
6163
* // results in:
6264
* // 0 -1000ms-> 1 -1000ms-> 2 -1000ms-> 3 -immediate-> 1 ... 10
65+
* ```
6366
*
64-
*
65-
* @example <caption>Concatenate an array of 3 Observables</caption>
67+
* ### Concatenate an array of 3 Observables
6668
* var timer1 = Rx.Observable.interval(1000).take(10);
6769
* var timer2 = Rx.Observable.interval(2000).take(6);
6870
* var timer3 = Rx.Observable.interval(500).take(10);
@@ -74,9 +76,10 @@ export function concat<T, R>(...observables: (ObservableInput<any> | SchedulerLi
7476
* // -1000ms-> 0 -1000ms-> 1 -1000ms-> ... 9
7577
* // -2000ms-> 0 -2000ms-> 1 -2000ms-> ... 5
7678
* // -500ms-> 0 -500ms-> 1 -500ms-> ... 9
79+
* ```
7780
*
78-
*
79-
* @example <caption>Concatenate the same Observable to repeat it</caption>
81+
* ### Concatenate the same Observable to repeat it
82+
* ```javascript
8083
* const timer = Rx.Observable.interval(1000).take(2);
8184
*
8285
* Rx.Observable.concat(timer, timer) // concating the same Observable!
@@ -92,6 +95,7 @@ export function concat<T, R>(...observables: (ObservableInput<any> | SchedulerLi
9295
* // 0 after 3s
9396
* // 1 after 4s
9497
* // "...and it is done!" also after 4s
98+
* ```
9599
*
96100
* @see {@link concatAll}
97101
* @see {@link concatMap}

‎src/internal/observable/defer.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,9 @@ import { empty } from './empty';
2121
* same Observable, in fact each subscriber gets its own individual
2222
* Observable.
2323
*
24-
* @example <caption>Subscribe to either an Observable of clicks or an Observable of interval, at random</caption>
24+
* ## Example
25+
* ### Subscribe to either an Observable of clicks or an Observable of interval, at random
26+
* ```javascript
2527
* var clicksOrInterval = Rx.Observable.defer(function () {
2628
* if (Math.random() > 0.5) {
2729
* return Rx.Observable.fromEvent(document, 'click');
@@ -36,6 +38,7 @@ import { empty } from './empty';
3638
* // for clicks anywhere on the "document"; when document is clicked it
3739
* // will log a MouseEvent object to the console. If the result is less
3840
* // than 0.5 it will emit ascending numbers, one every second(1000ms).
41+
* ```
3942
*
4043
* @see {@link create}
4144
*

‎src/internal/observable/dom/AjaxObservable.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,9 +110,11 @@ export class AjaxObservable<T> extends Observable<T> {
110110
* Creates an observable for an Ajax request with either a request object with
111111
* url, headers, etc or a string for a URL.
112112
*
113-
* @example
113+
* ## Example
114+
* ```javascript
114115
* source = Rx.Observable.ajax('/products');
115116
* source = Rx.Observable.ajax({ url: 'products', method: 'GET' });
117+
* ```
116118
*
117119
* @param {string|Object} request Can be one of the following:
118120
* A string of the URL to make the Ajax call.

‎src/internal/observable/dom/webSocket.ts‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,9 @@ import { WebSocketSubject, WebSocketSubjectConfig } from './WebSocketSubject';
33
/**
44
* Wrapper around the w3c-compatible WebSocket object provided by the browser.
55
*
6-
* @example <caption>Wraps browser WebSocket</caption>
7-
*
6+
* ## Examples
7+
* ### Wrapping browser WebSocket
8+
* ```javascript
89
* import { webSocket } from 'rxjs/webSocket';
910
*
1011
* let socket$ = webSocket('ws://localhost:8081');
@@ -16,9 +17,10 @@ import { WebSocketSubject, WebSocketSubjectConfig } from './WebSocketSubject';
1617
* );
1718
*
1819
* socket$.next(JSON.stringify({ op: 'hello' }));
20+
* ```
1921
*
20-
* @example <caption>Wraps WebSocket from nodejs-webSocket (using node.js)</caption>
21-
*
22+
* ### Wraps nodejs-webSocket</caption>
23+
* ```javascript
2224
* import { webSocket } from 'rxjs/webSocket';
2325
* import { w3cwebSocket } from 'webSocket';
2426
*
@@ -34,6 +36,7 @@ import { WebSocketSubject, WebSocketSubjectConfig } from './WebSocketSubject';
3436
* );
3537
*
3638
* socket$.next(JSON.stringify({ op: 'hello' }));
39+
* ```
3740
*
3841
* @param {string | WebSocketSubjectConfig} urlConfigOrSource the source of the webSocket as an url or a structure defining the webSocket object
3942
* @return {WebSocketSubject}

‎src/internal/observable/empty.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,15 @@ export const EMPTY = new Observable<never>(subscriber => subscriber.complete());
2020
* emits the complete notification. It can be used for composing with other
2121
* Observables, such as in a {@link mergeMap}.
2222
*
23-
* @example <caption>Emit the number 7, then complete.</caption>
23+
* ## Examples
24+
* ### Emit the number 7, then complete
25+
* ```javascript
2426
* var result = Rx.Observable.empty().startWith(7);
2527
* result.subscribe(x => console.log(x));
28+
* ```
2629
*
27-
* @example <caption>Map and flatten only odd numbers to the sequence 'a', 'b', 'c'</caption>
30+
* ### Map and flatten only odd numbers to the sequence 'a', 'b', 'c'
31+
* ```javascript
2832
* var interval = Rx.Observable.interval(1000);
2933
* var result = interval.mergeMap(x =>
3034
* x % 2 === 1 ? Rx.Observable.of('a', 'b', 'c') : Rx.Observable.empty()
@@ -36,6 +40,7 @@ export const EMPTY = new Observable<never>(subscriber => subscriber.complete());
3640
* // x will occur every 1000ms
3741
* // if x % 2 is equal to 1 print abc
3842
* // if x % 2 is not equal to 1 nothing will be output
43+
* ```
3944
*
4045
* @see {@link create}
4146
* @see {@link never}

‎src/internal/observable/forkJoin.ts‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,9 @@ export function forkJoin<T>(...sources: ObservableInput<T>[]): Observable<T[]>;
6767
* all its arguments and puts them into an array. Note that project function will be called only
6868
* when output Observable is supposed to emit a result.
6969
*
70-
* @example <caption>Use forkJoin with operator emitting immediately</caption>
70+
* ## Examples
71+
* ### Use forkJoin with operator emitting immediately
72+
* ```javascript
7173
* import { forkJoin, of } from 'rxjs';
7274
*
7375
* const observable = forkJoin(
@@ -83,9 +85,10 @@ export function forkJoin<T>(...sources: ObservableInput<T>[]): Observable<T[]>;
8385
* // Logs:
8486
* // [4, 8]
8587
* // "This is how it ends!"
88+
* ```
8689
*
87-
*
88-
* @example <caption>Use forkJoin with operator emitting after some time</caption>
90+
* ### Use forkJoin with operator emitting after some time
91+
* ```javascript
8992
* import { forkJoin, interval } from 'rxjs';
9093
* import { take } from 'rxjs/operators';
9194
*
@@ -102,9 +105,10 @@ export function forkJoin<T>(...sources: ObservableInput<T>[]): Observable<T[]>;
102105
* // Logs:
103106
* // [2, 3] after 3 seconds
104107
* // "This is how it ends!" immediately after
108+
* ```
105109
*
106-
*
107-
* @example <caption>Use forkJoin with project function</caption>
110+
* ### Use forkJoin with project function
111+
* ```javascript
108112
* import { jorkJoin, interval } from 'rxjs';
109113
* import { take } from 'rxjs/operators';
110114
*
@@ -122,6 +126,7 @@ export function forkJoin<T>(...sources: ObservableInput<T>[]): Observable<T[]>;
122126
* // Logs:
123127
* // 5 after 3 seconds
124128
* // "This is how it ends!" immediately after
129+
* ```
125130
*
126131
* @see {@link combineLatest}
127132
* @see {@link zip}

0 commit comments

Comments
 (0)