Merge branch 'master' into docs-withLatestFrom

Author: ashwin-sureshkumar

src/operator-docs/combination/concat.ts

@@ -1,6 +1,116 @@
 import { OperatorDoc } from '../operator.model';
 
 export const concat: OperatorDoc = {
-  'name': 'concat',
-  'operatorType': 'combination'
+  name: 'concat',
+  operatorType: 'combination',
+  signature:
+    'public static concat(input1: ObservableInput, input2: ObservableInput, scheduler: Scheduler): Observable',
+  parameters: [
+    {
+      name: 'input1',
+      type: 'ObservableInput',
+      attribute: '',
+      description: 'An input Observable to concatenate with others.'
+    },
+    {
+      name: 'input2',
+      type: 'ObservableInput',
+      attribute: '',
+      description:
+        'An input Observable to concatenate with others. More than one input Observables may be given as argument.'
+    },
+    {
+      name: 'scheduler',
+      type: 'Scheduler',
+      attribute: 'optional default: null',
+      description:
+        'An optional IScheduler to schedule each Observable subscription on.'
+    }
+  ],
+  marbleUrl: 'http://reactivex.io/rxjs/img/concat.png',
+  shortDescription: {
+    description:
+      'Creates an output Observable which sequentially emits all values from given Observable and then moves on to the next.',
+    extras: [
+      {
+        type: 'Tip',
+        text:
+          'Concatenates multiple Observables together by sequentially emitting their values, one Observable after the other.'
+      }
+    ]
+  },
+  walkthrough: {
+    description: `
+      <p><span class='markdown-code'>concat</span> joins multiple Observables together, by subscribing to them one at a time and
+      merging their results into the output Observable. You can pass either an array of
+      Observables, or put them directly as arguments. Passing an empty array will result
+      in Observable that completes immediately.</p>
+
+      <p><span class='markdown-code'>concat</span> will subscribe to first input Observable and emit all its values, without
+      changing or affecting them in any way. When that Observable completes, it will
+      subscribe to then next Observable passed and, again, emit its values. This will be
+      repeated, until the operator runs out of Observables. When last input Observable completes,
+      <span class='markdown-code'>concat</span> will complete as well. At any given moment only one Observable passed to operator
+      emits values. If you would like to emit values from passed Observables concurrently, check out
+      <a href='/#/operators/merge' class='markdown-code'>merge</a> instead, especially with optional
+      <span class='markdown-code'>concurrent</span> parameter.
+      As a matter of fact, <span class='markdown-code'>concat</span> is an equivalent of
+      <a href='/#/operators/merge' class='markdown-code'>merge</a> operator with
+      <span class='markdown-code'>concurrent</span> parameter set to <span class='markdown-code'>1</span>.</p>
+
+      <p>Note that if some input Observable never completes, <span class='markdown-code'>concat</span> will also never complete
+      and Observables following the one that did not complete will never be subscribed. On the other
+      hand, if some Observable simply completes immediately after it is subscribed, it will be
+      invisible for <span class='markdown-code'>concat</span>, which will just move on to the next Observable.</p>
+
+      <p>If any Observable in chain errors, instead of passing control to the next Observable,
+      <span class='markdown-code'>concat</span> will error immediately as well. Observables that would be subscribed after
+      the one that emitted error, never will.</p>
+
+      <p>If you pass to <span class='markdown-code'>concat</span> the same Observable many times, its stream of values
+      will be 'replayed' on every subscription, which means you can repeat given Observable
+      as many times as you like. If passing the same Observable to <span class='markdown-code'>concat</span> 1000 times becomes tedious,
+      you can always use <span class='markdown-code'>repeat</span>.</p>
+    `
+  },
+  examples: [
+    {
+      name:
+        'Concatenate a timer counting from 0 to 3 with a synchronous sequence from 1 to 10',
+      code: `
+      const timer = Rx.Observable.interval(1000).take(4);
+      const sequence = Rx.Observable.range(1, 10);
+      const result = Rx.Observable.concat(timer, sequence);
+      result.subscribe(x => console.log(x));
+
+      // results in:
+      // 0 -1000ms-> 1 -1000ms-> 2 -1000ms-> 3 -immediate-> 1 ... 10
+    `,
+      externalLink: {
+        platform: 'JSBin',
+        url: 'http://jsbin.com/doqoyimaxu/embed?js,console'
+      }
+    },
+    {
+      name: 'Concatenate an array of 3 Observables',
+      code: `
+      const timer1 = Rx.Observable.interval(1000).take(10);
+      const timer2 = Rx.Observable.interval(2000).take(6);
+      const timer3 = Rx.Observable.interval(500).take(10);
+      const result = timer1.concat(timer2, timer3);
+      result.subscribe(x => console.log(x));
+
+      // results in the following:
+      // (Prints to console sequentially)
+      // -1000ms-> 0 -1000ms-> 1 -1000ms-> ... 9
+      // -2000ms-> 0 -2000ms-> 1 -2000ms-> ... 5
+      // -500ms-> 0 -500ms-> 1 -500ms-> ... 9
+    `,
+      externalLink: {
+        platform: 'JSBin',
+        url: 'http://jsbin.com/decaromone/1/embed?js,console'
+      }
+    }
+  ],
+  relatedOperators: ['concatAll', 'concatMap', 'concatMapTo']
 };

src/operator-docs/combination/startWith.ts

@@ -1,6 +1,27 @@
 import { OperatorDoc } from '../operator.model';
 
 export const startWith: OperatorDoc = {
-  'name': 'startWith',
-  'operatorType': 'combination'
+  name: 'startWith',
+  operatorType: 'combination',
+  marbleUrl: 'http://reactivex.io/rxjs/img/startWith.png',
+  signature: 'public startWith(values: ...T, scheduler: Scheduler): Observable',
+  shortDescription: {
+    description:
+      'Returns an Observable that emits the items you specify as arguments before it begins to emit items emitted by the source Observable.'
+  },
+  parameters: [
+    {
+      name: 'values',
+      type: '...T',
+      attribute: '',
+      description: 'Items you want the modified Observable to emit first.'
+    },
+    {
+      name: 'scheduler',
+      type: 'Scheduler',
+      attribute: 'optional',
+      description:
+        'A IScheduler to use for scheduling the emissions of the next notifications.'
+    }
+  ]
 };

src/operator-docs/filtering/filter.ts

@@ -1,6 +1,79 @@
 import { OperatorDoc } from '../operator.model';
 
 export const filter: OperatorDoc = {
-  'name': 'filter',
-  'operatorType': 'filtering'
+  name: 'filter',
+  operatorType: 'filtering',
+  signature:
+    'public filter(predicate: function(value: T, index: number): boolean, thisArg: any): Observable',
+  parameters: [
+    {
+      name: 'predicate',
+      type: 'function(value: T, index: number): boolean',
+      attribute: '',
+      description: `A function that evaluates each value emitted by the source Observable.
+         If it returns true, the value is emitted, if false the value is not passed to the output Observable.
+        The index parameter is the number i for the i-th source emission that has happened since the subscription,
+         starting from the number 0.`
+    },
+    {
+      name: 'thisArg',
+      type: 'any',
+      attribute: 'optional',
+      description:
+        'An optional argument to determine the value of this in the predicate function.'
+    }
+  ],
+  marbleUrl: 'http://reactivex.io/rxjs/img/filter.png',
+  shortDescription: {
+    description:
+      'Filter items emitted by the source Observable by only emitting those that satisfy a specified predicate.',
+    extras: [
+      {
+        type: 'Tip',
+        text: `
+        Like
+        <a
+         target="_blank"
+         href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter">
+          Array.prototype.filter()
+        </a>,
+        it only emits a value from the source if it passes a criterion function.
+        `
+      }
+    ]
+  },
+  walkthrough: {
+    description: `
+      <p>
+        Similar to the well-known <span class="markdown-code">Array.prototype.filter</span>
+         method, this operator takes values from the source Observable,
+         passes them through a predicate function and only emits those values that yielded true.
+      </p>
+    `
+  },
+  examples: [
+    {
+      name: 'Filter for even numbers',
+      code: `
+      //emit (1,2,3,4,5)
+      const source = Rx.Observable.from([1, 2, 3, 4, 5]);
+      //filter out non-even numbers
+      const example = source.filter(num => num % 2 === 0);
+      //output: "Even number: 2", "Even number: 4"
+      const subscribe = example.subscribe(val => console.log('Even number: ' + val));
+      `,
+      externalLink: {
+        platform: 'JSBin',
+        url: 'http://jsbin.com/vafogoluye/1/embed?js,console'
+      }
+    }
+  ],
+  relatedOperators: [
+    'distinct',
+    'distinctUntilChanged',
+    'distinctUntilKeyChanged',
+    'ignoreElements',
+    'partition',
+    'skip'
+  ]
 };

src/operator-docs/filtering/skip.ts

@@ -1,6 +1,38 @@
 import { OperatorDoc } from '../operator.model';
 
 export const skip: OperatorDoc = {
-  'name': 'skip',
-  'operatorType': 'filtering'
+  name: 'skip',
+  operatorType: 'filtering',
+  signature: 'public skip(count: Number): Observable',
+  parameters: [
+    {
+      name: 'count',
+      type: 'Number',
+      attribute: '',
+      description:
+        'Returns an Observable that skips the first count items emitted by the source Observable.'
+    }
+  ],
+  marbleUrl: 'http://reactivex.io/rxjs/img/skip.png',
+  shortDescription: {
+    description:
+      'Returns an Observable that skips the first count items emitted by the source Observable.'
+  },
+  examples: [
+    {
+      name: 'Skipping values before emission',
+      code: `
+      //emit every 1s
+      const source = Rx.Observable.interval(1000);
+      //skip the first 5 emitted values
+      const example = source.skip(5);
+      //output: 5...6...7...8........
+      const subscribe = example.subscribe(val => console.log(val));
+      `,
+      externalLink: {
+        platform: 'JSBin',
+        url: 'http://jsbin.com/hacepudabi/1/embed?js,console'
+      }
+    }
+  ]
 };

src/operator-docs/filtering/take.ts

@@ -1,6 +1,57 @@
 import { OperatorDoc } from '../operator.model';
 
 export const take: OperatorDoc = {
-  'name': 'take',
-  'operatorType': 'filtering'
+  name: 'take',
+  operatorType: 'filtering',
+  signature: 'public take(count: number): Observable<T>',
+  useInteractiveMarbles: true,
+  parameters: [
+    {
+      name: 'count',
+      type: 'number',
+      attribute: '',
+      description: 'The maximum number of next values to emit.'
+    }
+  ],
+  marbleUrl: 'http://reactivex.io/rxjs/img/take.png',
+  shortDescription: {
+    description: `Emits only the first count values emitted by the source Observable.`,
+    extras: [
+      {
+        type: 'Tip',
+        text: `Takes the first count values from the source, then completes.`
+      }
+    ]
+  },
+  walkthrough: {
+    description: `<p>
+      <span class="markdown-code">take</span> returns an Observable that emits only the first count values emitted by the source Observable.
+    </p>
+    <p>
+      If the source emits fewer than count values then all of its values are emitted.
+      After that, it completes, regardless if the source completes.
+    </p>`
+  },
+  examples: [
+    {
+      name:
+        'Take the first 5 seconds of an infinite 1-second interval Observable',
+      code: `
+      const interval = Rx.Observable.interval(1000);
+      const five = interval.take(5);
+      five.subscribe(x => console.log(x));
+      // Logs below values
+      // 0
+      // 1
+      // 2
+      // 3
+      // 4
+      `,
+      externalLink: {
+        platform: 'JSBin',
+        url: 'http://jsbin.com/yujema/embed?html,js,console'
+      }
+    }
+  ],
+  relatedOperators: ['takeLast', 'takeUntil', 'takeWhile', 'skip']
 };