docs(operators): examples for catch operator

src/operator/catch.ts

@@ -7,6 +7,54 @@ import { subscribeToResult } from '../util/subscribeToResult';
 
 /**
  * Catches errors on the observable to be handled by returning a new observable or throwing an error.
+ *
+ * <img src="./img/catch.png" width="100%">
+ * 
+ * @example <caption>Continues with a different Observable when there's an error</caption>
+ * 
+ * Observable.of(1, 2, 3, 4, 5)
+ *   .map(n => { 
+ * 	   if (n == 4) {
+ * 	     throw 'four!';
+ *     }
+ *	   return n; 
+ *   })
+ *   .catch(err => Observable.of('I', 'II', 'III', 'IV', 'V'))
+ *   .subscribe(x => console.log(x));
+ *   // 1, 2, 3, I, II, III, IV, V
+ *
+ * @example <caption>Retries the caught source Observable again in case of error, similar to retry() operator</caption>
+ *
+ * Observable.of(1, 2, 3, 4, 5)
+ *   .map(n => { 
+ * 	   if (n === 4) {
+ * 	     throw 'four!'; 
+ *     }
+ * 	   return n; 
+ *   })
+ *   .catch((err, caught) => caught)
+ *   .take(30)
+ *   .subscribe(x => console.log(x));
+ *   // 1, 2, 3, 1, 2, 3, ...
+ * 
+ * @example <caption>Throws a new error when the source Observable throws an error</caption>
+ * 
+ * Observable.of(1, 2, 3, 4, 5)
+ *   .map(n => { 
+ *     if (n == 4) {
+ *       throw 'four!';
+ *     }
+ *     return n; 
+ *   })
+ *   .catch(err => {
+ *     throw 'error in source. Details: ' + err;
+ *   })
+ *   .subscribe(
+ *     x => console.log(x),
+ *     err => console.log(err)
+ *   );
+ *   // 1, 2, 3, error in source. Details: four!
+ * 
  * @param {function} selector a function that takes as arguments `err`, which is the error, and `caught`, which
  *  is the source observable, in case you'd like to "retry" that observable by returning it again. Whatever observable
  *  is returned by the `selector` will be used to continue the observable chain.