fix(docs): fix code examples (#3784)

src/internal/Observable.ts

@@ -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) {
@@ -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)
@@ -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,
@@ -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
@@ -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)
@@ -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) {

src/internal/observable/bindCallback.ts

@@ -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'
@@ -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();
  * }
@@ -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}

src/internal/observable/bindNodeCallback.ts

@@ -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
@@ -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
  * });
@@ -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}

src/internal/observable/combineLatest.ts

@@ -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);
@@ -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
  * );
@@ -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));
@@ -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}

src/internal/observable/concat.ts

@@ -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);
@@ -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!
@@ -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}

src/internal/observable/defer.ts

@@ -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');
@@ -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}
  *

src/internal/observable/dom/AjaxObservable.ts

@@ -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.

src/internal/observable/dom/webSocket.ts

@@ -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');
@@ -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';
  *
@@ -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}

src/internal/observable/empty.ts

@@ -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()
@@ -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}

src/internal/observable/forkJoin.ts

@@ -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(
@@ -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';
  *
@@ -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';
  *
@@ -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}