docs(operators): add documentation for bufferWhen (#236)

* docs(operations): add documentation for bufferWhen to close #113

Add documentation for operator bufferWhen to close #113

#113

* fix(build): Fix Travis CI build

Add dependency for @angular-devkit/core to fix the Travis CI build

* revert(dependencies): Modify package.json to use the latest angular-cli

As an temporary solution I added @angular-devkit/core as a devDependency to solve the build issues
from Travis. However, I now changed the package.json to include the latest angular-cli version (to
1.6.5) and this allows Travis to build correctly. I find this a better solution than the previous
one

* fix(operators): Modify windowTime to windowWhen

The related operators was listing windowTime, but instead should be listing windowWhen

* refactor(operators): Add comment for expected output on console

Added comment in the documentation as requested to contain the expected console output. Removed the
$ suffix from the examples for now for consistency (wait for coding guidelines).

* style(operators): Move expected console output after subscription

The expected console output should be after the subscription. Also deleted the generics from the
method signature.

Author: DiedrikDM

src/operator-docs/transformation/bufferWhen.ts

@@ -1,6 +1,166 @@
 import { OperatorDoc } from '../operator.model';
 
 export const bufferWhen: OperatorDoc = {
-  'name': 'bufferWhen',
-  'operatorType': 'transformation'
+  name: 'bufferWhen',
+  operatorType: 'transformation',
+  signature: `bufferWhen(closingSelector: () => Observable): Observable`,
+  parameters: [
+    {
+      name: 'closingSelector',
+      type: '() => Observable',
+      attribute: '',
+      description: `A function that takes no arguments and returns an Observable that signals buffer closure.`
+    }
+  ],
+  marbleUrl: 'http://reactivex.io/rxjs/img/bufferWhen.png',
+  shortDescription: {
+    description: `Buffers the source Observable values, using a factory function of closing Observables
+     to determine when to close, emit, and reset the buffer.
+    <span class="informal">Collects values from the past as an array.
+     When it starts collecting values, it calls a function that returns an Observable that tells
+      when to close the buffer and restart collecting.</span>`
+  },
+  walkthrough: {
+    description: `
+    Opens a buffer immediately, then closes the buffer when the observable returned by calling
+    <span class="markdown-code">closingSelector</span> function emits a value.
+     When it closes the buffer, it immediately opens a new buffer and repeats the process.`
+  },
+  examples: [
+    {
+      name: 'Emit an array of the last clicks every [1-5] random seconds',
+      code: `
+      import { fromEvent } from 'rxjs/observable/fromEvent';
+      import { interval  } from 'rxjs/observable/interval';
+      import { bufferWhen } from 'rxjs/operators';
+
+      const clicks = fromEvent(document, 'click', e => ({x: e.clientX, y: e.clientY}));
+      const buffered = clicks.pipe(
+        bufferWhen(() => interval(1000 + Math.random() * 4000))
+      )
+      buffered.subscribe(x => console.log(x));
+
+      /*
+      Example console output:
+
+      []
+
+      []
+
+      [[object Object] {
+        x: 87,
+        y: 222
+      }, [object Object] {
+        x: 87,
+        y: 222
+      }, [object Object] {
+        x: 100,
+        y: 228
+      }, [object Object] {
+        x: 151,
+        y: 296
+      }]
+
+      [[object Object] {
+        x: 130,
+        y: 368
+      }, [object Object] {
+        x: 132,
+        y: 368
+      }, [object Object] {
+        x: 227,
+        y: 212
+      }, [object Object] {
+        x: 189,
+        y: 321
+      }, [object Object] {
+        x: 160,
+        y: 411
+      }, [object Object] {
+        x: 160,
+        y: 411
+      }, [object Object] {
+        x: 155,
+        y: 366
+      }]
+
+      []
+      */
+      `,
+      externalLink: {
+        platform: 'JSBin',
+        url: 'http://jsbin.com/jemeron/9/embed?js,console,output'
+      }
+    },
+    {
+      name: 'Buffer all the click events until you press the Enter key',
+      code: `
+      import { fromEvent } from 'rxjs/observable/fromEvent';
+      import { filter, bufferWhen } from 'rxjs/operators';
+
+      const enterKeys = fromEvent(document,'keyup')
+                          .pipe(filter(e => e.key === "Enter"));
+      const clicks = fromEvent(document, 'click', e => ({x: e.clientX, y: e.clientY}));
+      const buffered = clicks.pipe(
+        bufferWhen(() => enterKeys)
+      );
+      buffered.subscribe(x => console.log(x));
+
+      /*
+      Example console output:
+
+      [[object Object] {
+        x: 186,
+        y: 136
+      }, [object Object] {
+        x: 188,
+        y: 136
+      }, [object Object] {
+        x: 189,
+        y: 136
+      }, [object Object] {
+        x: 189,
+        y: 136
+      }, [object Object] {
+        x: 192,
+        y: 136
+      }]
+
+      [[object Object] {
+        x: 196,
+        y: 135
+      }, [object Object] {
+        x: 196,
+        y: 135
+      }]
+
+      [[object Object] {
+        x: 198,
+        y: 125
+      }]
+
+      [[object Object] {
+        x: 196,
+        y: 135
+      }, [object Object] {
+        x: 196,
+        y: 135
+      }]
+
+      []
+      */
+`,
+      externalLink: {
+        platform: 'JSBin',
+        url: 'http://jsbin.com/tuvesok/5/embed?js,console,output'
+      }
+    }
+  ],
+  relatedOperators: [
+    'buffer',
+    'bufferCount',
+    'bufferTime',
+    'bufferToggle',
+    'windowWhen'
+  ]
 };