docs(operators): examples for catch operator

src/operator/catch.ts

@@ -7,6 +7,45 @@ import { subscribeToResult } from '../util/subscribeToResult';
 
 /**
  * Catches errors on the observable to be handled by returning a new observable or throwing an error.
+ *
+ * @example <caption>Returns a different Observable in case of error</caption>
+ * 
+ * let primary$ = Observable.of(1, 2, 3, 4, 5);
+ * let secondary$ = Observable.of('I', 'II', 'III', 'IV', 'V');
+ * 
+ * primary$
+ *     .map(n => { 
+ * 	if (n == 4) 
+ * 	    throw 'four!'; 
+ * 	return n; 
+ *     })
+ *     .catch(err => secondary$)
+ * 	.subscribe(x => console.log(x)); // -> 1, 2, 3, I, II, III, IV, V
+ *
+ * @example <caption>"Tries" the Observable again in case of error</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.