docs(operators): add documentation for concatMap

src/operator-docs/transformation/concatMap.ts

@@ -1,6 +1,78 @@
 import { OperatorDoc } from '../operator.model';
 
 export const concatMap: OperatorDoc = {
-  'name': 'concatMap',
-  'operatorType': 'transformation'
+  name: 'concatMap',
+  operatorType: 'transformation',
+  signature: `concatMap(project: (value: T, index: number) =>  ObservableInput<I>,
+  ?resultSelector: (outerValue: T, innerValue: I, outerIndex: number, innerIndex: number) => R): Observable`,
+  parameters: [
+    {
+      name: 'project',
+      type: 'function(value: T, index: number): ObservableInput',
+      attribute: '',
+      description: `A function that, when applied to an item emitted by the source
+       Observable, returns an Observable.`
+    },
+    {
+      name: 'resultSelector',
+      type:
+        'function(outerValue: T, innerValue: I, outerIndex: number, innerIndex: number): any',
+      attribute: 'optional',
+      description: `A function to produce the value on the output Observable based on the values
+      and the indices of the source (outer) emission and the inner Observable
+      emission. The arguments passed to this function are:
+      - 'outerValue': the value that came from the source.
+      - 'innerValue': the value that came from the projected Observable.
+      - 'outerIndex': the "index" of the value that came from the source.
+      - 'innerIndex': the "index" of the value from the projected Observable.`
+    }
+  ],
+  marbleUrl: 'http://reactivex.io/rxjs/img/concatMap.png',
+  shortDescription: {
+    description: `Project each source value to an Observable which is merge in the output observable,
+    in a serialized fashion waiting for each one to complete before merging the next one
+    <span class="informal">Maps each value to an Observable, then flattens all of
+    these inner Observables using <a href="#/operators/concatAll">concatAll</a>.</span>`
+  },
+  walkthrough: {
+    description: `the source observable maps values to inner observable, subscribe and emit in order.
+     After subscribing the source observable is ended therefore the concatMap's project function
+     is only executed once. the second parameter 'resultFunction', allows you to access to the index of
+     source observable and inner observable (besides the items)`
+  },
+  examples: [
+    {
+      name:
+        'Map the first click to inner observable (it ended the Observable of clicks)',
+      code: `
+      import { Observable } from 'rxjs/Observable';
+      import { interval } from 'rxjs/observable/interval';
+      import { fromEvent } from 'rxjs/observable/fromEvent';
+
+      import { mapTo, concatMap } from 'rxjs/operators';
+
+      const $click = fromEvent(document, 'click');
+      const $interval = interval(3000)
+          .pipe(mapTo((iClick, iInterval) => 'Click('+iClick+')'+', '+'Interval('+iInterval+')'));
+      // the ConcatMap's project function is executed just one time!
+      // Even if you make aditional cliks the ConcatMap's project function is not longer executed
+      // output; Click(0), Interval(0) -> Click(0), Interval(1) -> Click(0), Interval(2) -> etc
+      $click.pipe(concatMap(() => $interval,
+          (fromSource, fromInterval, indexSource, indexInterval) => fromInterval(indexSource, indexInterval)))
+          .subscribe(console.log);
+      `,
+      externalLink: {
+        platform: 'JSBin',
+        url: 'https://stackblitz.com/edit/concatmap?file=index.ts'
+      }
+    }
+  ],
+  relatedOperators: [
+    'concat',
+    'concatAll',
+    'concatMapTo',
+    'exhaustMap',
+    'mergeMap',
+    'switchMap'
+  ]
 };