Merge branch 'master' into docs-operator-mergemap

Author: sumitarora

DOCUMENTATION_GUIDELINES.md

@@ -0,0 +1,160 @@
+# Documentation Guidelines
+
+This document is a work in progress and contains the _current_ guidelines that should be followed when working on documentation.
+
+This document is _not_ a holy scripture and we're always open for discussion. 
+However when an agreement is found, you should follow this document to keep the documentation consistent. 
+
+If you're not sure, contact us on our Slack Channel (see [#4](https://github.com/ReactiveX/rxjs-docs/issues/4) or [#24](https://github.com/ReactiveX/rxjs-docs/issues/24) for more information on that).
+
+## TL;DR
+>_Sorry, but you will need take your time reading the document if you want to know more about the guidelines._ 
+
+This document talks about the [structure of the operator documentation](#documentation-format), [the method signature](#method-signature) and the guidelines in our [code examples](#code-examples).
+
+## Documentation Format
+The documentation is created in a ts file under src/operator-docs. 
+Normally the file for the operator should already have been created.
+If that's not the case, recheck all subfolders/categories to be sure (it's easy to overlook with all of those operators).
+If you still cannot find the operator, create the file in the category that most fits the use case.
+
+The ts file contains an object that implements the __OperatorDoc__ interface. All properties are optional:
+
+- __name__: the name of your operator
+- __operatorType__: any one of these strings 'combination'
+  | 'conditional'
+  | 'creation'
+  | 'error handling'
+  | 'filtering'
+  | 'multicasting'
+  | 'transformation'
+  | 'utility'
+- __signature__: the signature of the operator method (without using generics)
+- __useInteractiveMarbles__: currently not used, but should be true for an interactive marble diagram
+- __marbleUrl__: the url for a marble diagram (use the existing image url found on http://reactivex.io/rxjs for a static diagram)
+- __parameters__: OperatorParameters[]. Every OperatorParameters implementation takes 
+  - the _name_ of the parameter
+  - the _type_ (string, number, Observable,...)
+  - the _attribute_ (optional,...)
+  - the _description_ explaining what the parameter is used for
+- __shortDescription__: {
+    description: string;
+    extras?: OperatorExtra[]
+  }
+  - [HTML] the short _description_ of what the operator does (a TL;DR text)
+  - _extras_ containing a type of 'Tip'|'Warning' and some text for it. It will show up with a little icon to make the type of extra clear.
+- __walkthrough__: {
+    description: string;
+    extras?: OperatorExtra[]
+  }
+  - [HTML] the long and well explained _description_ of what the operator does (the technically correct description and explanation)
+  - _extras_ containing a type of 'Tip'|'Warning' and some text for it. It will show up with a little icon to make the type of extra clear.
+- __examples__: one or more examples demonstrating the use of the operator
+  - _name_: Text explaining what the example code does
+  - _code_: The code used in your example. This code will get copied if the user clicks on the copy icon above the code example.
+  - _externalLink_: an object containing a type of 'JSBin'|'JSFiddle' and the url towards a working example. (Talks are underway to also support Stackblitz in the near future)
+- __additionalResources__: OperatorReference[]
+  - _url_ towards an additional resource explaining the operator (like a blog post, youtube video,...)
+  - _description_ used as text for the link
+  - _author_: the author of the resource (currently not used/shown)
+- __relatedOperators__: names of other operators related to the current one
+
+## Method signature
+The signature of the method should contain the correct name, parameters and return type of the method. 
+We don't want to show any generics (like <T>) in the signature, because in most cases it does not add any value.
+See [#196](https://github.com/ReactiveX/rxjs-docs/pull/196#discussion_r155799478) for the discussion on this topic.
+
+## Code examples
+In the example code we want to make use of ES6/TS imports as well as the pipeable operators. 
+See [#196](https://github.com/ReactiveX/rxjs-docs/pull/196#discussion_r157232289) for a discussion on this topic.
+However, neither jsbin nor jsfiddle support this format. When the project gets support from Stackblitz, the newer syntax should be available on that platform and is of course preferred.
+
+Currently to have the best of both worlds, try to follow this guideline:
+- The code created directly in the ts file (which will get copied when you click on the icon) should follow the ES6/TS imports and pipeable operators.
+- The code in the running example on jsbin/jsfiddle should work, so in other words, use the older syntax.
+
+The example code should also contain a comment which shows the expected output on the console.
+This comment should be put after/below the subscribe call on the observable.
+
+In our examples we are currently not making use of the finnish notation ($ suffix). To be consistent with the other examples, neither should you.
+
+Here's an example for both the inline code as well as one on jsbin:
+
+__INLINE__
+```javascript
+import { fromEvent } from 'rxjs/observable/fromEvent';
+import { bufferCount } from 'rxjs/operators';
+
+const clicks = fromEvent(document, 'click', e => ({x: e.clientX, y: e.clientY}));
+const buffered = clicks.pipe(
+  bufferCount(2)
+);
+buffered.subscribe(x => console.log(x));
+
+/*
+  Example console output:
+
+  [[object Object] {
+    x: 235,
+    y: 140
+  }, [object Object] {
+    x: 63,
+    y: 45
+  }]
+
+  [[object Object] {
+    x: 199,
+    y: 74
+  }, [object Object] {
+    x: 133,
+    y: 181
+  }]
+
+  [[object Object] {
+    x: 343,
+    y: 174
+  }, [object Object] {
+    x: 274,
+    y: 82
+  }]
+*/
+
+```
+
+__JSBIN__
+```javascript
+const clicks = Rx.Observable.fromEvent(document, 'click', e => ({x: e.clientX, y: e.clientY}));
+const buffered = clicks.bufferCount(2);
+buffered.subscribe(x => console.log(x));
+/*
+  Example console output:
+
+  [[object Object] {
+    x: 235,
+    y: 140
+  }, [object Object] {
+    x: 63,
+    y: 45
+  }]
+
+  [[object Object] {
+    x: 199,
+    y: 74
+  }, [object Object] {
+    x: 133,
+    y: 181
+  }]
+
+  [[object Object] {
+    x: 343,
+    y: 174
+  }, [object Object] {
+    x: 274,
+    y: 82
+  }]
+*/
+
+```
+
+
+

src/operator-docs/combination/combineAll.ts

@@ -51,12 +51,19 @@ export const combineAll: OperatorDoc = {
       name:
         'Map two click events to a finite interval Observable, then apply <span class="markdown-code">combineAll</span>',
       code: `
-        const clicks = Rx.Observable.fromEvent(document, 'click');
-        const higherOrder = clicks.map(ev =>
-          Rx.Observable.interval(Math.random()*2000).take(3)
-        )
-        .take(2);
-        const result = higherOrder.combineAll();
+        import { map, combineAll, take } from 'rxjs/operators';
+        import { fromEvent } from 'rxjs/observable/fromEvent';
+
+        const clicks = fromEvent(document, 'click');
+        const higherOrder = clicks.pipe(
+          map(ev =>
+            interval(Math.random()*2000).pipe(take(3))
+          ),
+          take(2)
+        );
+        const result = higherOrder.pipe(
+          combineAll()
+        );
         result.subscribe(x => console.log(x));
       `,
       externalLink: {

src/operator-docs/combination/combineLatest.ts

@@ -56,9 +56,14 @@ export const combineLatest: OperatorDoc = {
       name:
         'Dynamically calculate the Body-Mass Index from an Observable of weight and one for height',
       code: `
-        const weight = Rx.Observable.of(70, 72, 76, 79, 75);
-        const height = Rx.Observable.of(1.76, 1.77, 1.78);
-        const bmi = weight.combineLatest(height, (w, h) => w / (h * h));
+        import { combineLatest } from 'rxjs/operators;
+        import { of } from 'rxjs/observable/of';
+
+        const weight = of(70, 72, 76, 79, 75);
+        const height = of(1.76, 1.77, 1.78);
+        const bmi = weight.pipe(
+          combineLatest(height, (w, h) => w / (h * h))
+        );
         /*
            Output:
            BMI is 24.212293388429753

src/operator-docs/combination/concat.ts

@@ -78,9 +78,14 @@ export const concat: OperatorDoc = {
       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);
+      import { take } from 'rxjs/operators';
+      import { interval } from 'rxjs/observable/interval';
+      import { range } from 'rxjs/observable/range';
+      import { concat } from 'rxjs/observable/concat';
+
+      const timer = interval(1000).pipe(take(4));
+      const sequence = range(1, 10);
+      const result = concat(timer, sequence);
       result.subscribe(x => console.log(x));
 
       // results in:
@@ -94,10 +99,13 @@ export const concat: OperatorDoc = {
     {
       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);
+      import { take, concat } from 'rxjs/operators';
+      import { interval } from 'rxjs/observable/interval';
+
+      const timer1 = interval(1000).pipe(take(10));
+      const timer2 = interval(2000).pipe(take(6));
+      const timer3 = interval(500).pipe(take(10));
+      const result = timer1.pipe(concat(timer2, timer3));
       result.subscribe(x => console.log(x));
 
       // results in the following:

src/operator-docs/combination/concatAll.ts

@@ -42,9 +42,15 @@ export const concatAll: OperatorDoc = {
       name:
         'For each click event, tick every second from 0 to 3, with no concurrency',
       code: `
-        const clicks = Rx.Observable.fromEvent(document, 'click');
-        const higherOrder = clicks.map(ev => Rx.Observable.interval(1000).take(4));
-        const firstOrder = higherOrder.concatAll();
+        import { map, take, concatAll } from 'rxjs/operators';
+        import { fromEvent } from 'rxjs/observable/fromEvent';
+        import { interval } from 'rxjs/observable/interval';
+
+        const clicks = fromEvent(document, 'click');
+        const higherOrder = clicks.pipe(
+          map(ev => interval(1000).pipe(take(4)))
+        );
+        const firstOrder = higherOrder.pipe(concatAll());
         firstOrder.subscribe(x => console.log(x));
       `,
       externalLink: {

src/operator-docs/combination/forkJoin.ts

@@ -73,9 +73,12 @@ export const forkJoin: OperatorDoc = {
     {
       name: 'Use forkJoin with operator emitting immediately',
       code: `
-      const observable = Rx.Observable.forkJoin(
-        Rx.Observable.of(1, 2, 3, 4),
-        Rx.Observable.of(5, 6, 7, 8)
+      import { forkJoin } from 'rxjs/observable/forkJoin';
+      import { of } from 'rxjs/observable/of';
+
+      const observable = forkJoin(
+        of(1, 2, 3, 4),
+        of(5, 6, 7, 8)
       );
       observable.subscribe(
         value => console.log(value),
@@ -94,9 +97,13 @@ export const forkJoin: OperatorDoc = {
     {
       name: 'Use forkJoin with operator emitting after some time',
       code: `
-      const observable = Rx.Observable.forkJoin(
-        Rx.Observable.interval(1000).take(3), // emit 0, 1, 2 every second and complete
-        Rx.Observable.interval(500).take(4) // emit 0, 1, 2, 3 every half a second and complete
+      import { take } from 'rxjs/operators';
+      import { forkJoin } from 'rxjs/observable/forkJoin';
+      import { interval } from 'rxjs/observable/interval';
+
+      const observable = forkJoin(
+        interval(1000).pipe(take(3)), // emit 0, 1, 2 every second and complete
+        interval(500).pipe(take(4)) // emit 0, 1, 2, 3 every half a second and complete
       );
       observable.subscribe(
         value => console.log(value),

src/operator-docs/combination/merge.ts

@@ -46,9 +46,13 @@ export const merge: OperatorDoc = {
     {
       name: 'Merge together two Observables: 1s interval and clicks',
       code: `
-        const clicks = Rx.Observable.fromEvent(document, 'click');
-        const timer = Rx.Observable.interval(1000);
-        const clicksOrTimer = clicks.merge(timer);
+        import { merge } from 'rxjs/operators';
+        import { fromEvent } from 'rxjs/observable/fromEvent';
+        import { interval } from 'rxjs/observable/interval';
+
+        const clicks = fromEvent(document, 'click');
+        const timer = interval(1000);
+        const clicksOrTimer = clicks.pipe(merge(timer));
         clicksOrTimer.subscribe(x => console.log(x));
       `,
       externalLink: {
@@ -59,11 +63,15 @@ export const merge: OperatorDoc = {
     {
       name: 'Merge together 3 Observables, but only 2 run concurrently',
       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);
+        import { take } from 'rxjs/operators';
+        import { merge } from 'rxjs/observable/merge';
+        import { interval } from 'rxjs/observable/interval';
+
+        const timer1 = interval(1000).pipe(take(10));
+        const timer2 = interval(2000).pipe(take(6));
+        const timer3 = interval(500).pipe(take(10));
         const concurrent = 2; // the argument
-        const merged = timer1.merge(timer2, timer3, concurrent);
+        const merged = timer1.pipe(merge(timer2, timer3, concurrent));
         merged.subscribe(x => console.log(x));
       `,
       externalLink: {

src/operator-docs/combination/mergeAll.ts

@@ -38,9 +38,13 @@ export const mergeAll: OperatorDoc = {
       name:
         'Spawn a new interval Observable for each click event, and blend their outputs as one Observable',
       code: `
-        const clicks = Rx.Observable.fromEvent(document, 'click');
-        const higherOrder = clicks.map((ev) => Rx.Observable.interval(1000));
-        const firstOrder = higherOrder.mergeAll();
+        import { mergeAll, map } from 'rxjs/operators';
+        import { fromEvent } from 'rxjs/observable/fromEvent';
+        import { interval } from 'rxjs/observable/interval';
+
+        const clicks = fromEvent(document, 'click');
+        const higherOrder = clicks.pipe(map((ev) => interval(1000)));
+        const firstOrder = higherOrder.pipe(mergeAll());
         firstOrder.subscribe(x => console.log(x));
       `,
       externalLink: {
@@ -52,9 +56,15 @@ export const mergeAll: OperatorDoc = {
       name:
         'Count from 0 to 9 every second for each click, but only allow 2 concurrent timers',
       code: `
-        const clicks = Rx.Observable.fromEvent(document, 'click');
-        const higherOrder = clicks.map((ev) => Rx.Observable.interval(1000).take(10));
-        const firstOrder = higherOrder.mergeAll(2);
+        import { mergeAll, map } from 'rxjs/operators';
+        import { fromEvent } from 'rxjs/observable/fromEvent';
+        import { interval } from 'rxjs/observable/interval';
+
+        const clicks = fromEvent(document, 'click');
+        const higherOrder = clicks.pipe(
+          map((ev) => interval(1000).pipe(take(10)))
+        );
+        const firstOrder = higherOrder.pipe(mergeAll(2));
         firstOrder.subscribe(x => console.log(x));
       `,
       externalLink: {

src/operator-docs/combination/pairwise.ts

@@ -30,15 +30,20 @@ export const pairwise: OperatorDoc = {
       name:
         'On every click (starting from the second), emit the relative distance to the previous click',
       code: `
-      const clicks = Rx.Observable.fromEvent(document, 'click');
-      const pairs = clicks.pairwise();
-      const distance = pairs.map(pair => {
-        const x0 = pair[0].clientX;
-        const y0 = pair[0].clientY;
-        const x1 = pair[1].clientX;
-        const y1 = pair[1].clientY;
-        return Math.sqrt(Math.pow(x0 - x1, 2) + Math.pow(y0 - y1, 2));
-      });
+      import { pairwise, map } from 'rxjs/operators';
+      import { fromEvent } from 'rxjs/observable/fromEvent';
+
+      const clicks = fromEvent(document, 'click');
+      const pairs = clicks.pipe(pairwise());
+      const distance = pairs.pipe(
+        map(pair => {
+          const x0 = pair[0].clientX;
+          const y0 = pair[0].clientY;
+          const x1 = pair[1].clientX;
+          const y1 = pair[1].clientY;
+          return Math.sqrt(Math.pow(x0 - x1, 2) + Math.pow(y0 - y1, 2));
+        })
+      );
       distance.subscribe(x => console.log(x));
     `,
       externalLink: {