docs(subscribe): update subscribe documentation

* docs(subscribe): add comma after "In particular"

* docs(subscribe): add notice about asynchronously thrown errors

* docs(subscribe): add notice about deprecated usages of `subscribe` method (relates to ReactiveX#4159)

* docs(subscribe): add notice about using `subscribe` with no params

* docs(subscribe): fix example not to use deprecated `subscribe`

* docs(subscribe): add example with deprecated `subscribe` with notice that it's deprecated

* docs(subscribe): fix unsubscribe example replacing deprecated `subscribe` usage with Observer

* docs(subscribe): add notice that unprovided error handlers will cause throwing errors asynchronously

* docs(subscribe): fix return type

Closes ReactiveX#5339

src/internal/Observable.ts

@@ -95,18 +95,27 @@ export class Observable<T> implements Subscribable<T> {
    *
    * The first way is creating an object that implements {@link Observer} interface. It should have methods
    * defined by that interface, but note that it should be just a regular JavaScript object, which you can create
-   * yourself in any way you want (ES6 class, classic function constructor, object literal etc.). In particular do
+   * yourself in any way you want (ES6 class, classic function constructor, object literal etc.). In particular, do
    * not attempt to use any RxJS implementation details to create Observers - you don't need them. Remember also
    * that your object does not have to implement all methods. If you find yourself creating a method that doesn't
-   * do anything, you can simply omit it. Note however, if the `error` method is not provided, all errors will
-   * be left uncaught.
+   * do anything, you can simply omit it. Note however, if the `error` method is not provided and an error happens,
+   * it will be asynchronously thrown. There is no way to catch asynchronously thrown errors by using try/catch as
+   * they are caught by the global error handler (`window.onerror` or `process.on('error)`, depending on the used
+   * runtime). So it's probably the best solution to provide `error` handler to avoid missing thrown errors.
    *
    * The second way is to give up on Observer object altogether and simply provide callback functions in place of its methods.
    * This means you can provide three functions as arguments to `subscribe`, where the first function is equivalent
    * of a `next` method, the second of an `error` method and the third of a `complete` method. Just as in case of Observer,
-   * if you do not need to listen for something, you can omit a function, preferably by passing `undefined` or `null`,
-   * since `subscribe` recognizes these functions by where they were placed in function call. When it comes
-   * to `error` function, just as before, if not provided, errors emitted by an Observable will be thrown.
+   * if you do not need to listen for something, you can omit a function. If you plan to omit a function, please keep in mind
+   * that there are some deprecated cases. Omitting a function is OK if you plan to omit last of them, i.e. if you plan to omit
+   * `complete` or both `error` and `complete`. Other cases where passing `undefined` or `null` after which you'd have an `error`
+   * or `complete` functions are deprecated. Though, it would still work since `subscribe` recognizes these functions by where
+   * they were placed in function call. E.g. providing `error` and `complete` functions without `next` is deprecated and this
+   * case should be handled by using Observer object. When it comes to `error` function, just as before, if not provided, an
+   * error emitted by an Observable will be asynchronously thrown.
+   *
+   * You can, however, subscribe with no parameters at all. This may be the case where you're not interested in terminal events
+   * and you also handled emissions internally by using operators (e.g. using `tap`).
    *
    * Whichever style of calling `subscribe` you use, in both cases it returns a Subscription object.
    * This object allows you to call `unsubscribe` on it, which in turn will stop the work that an Observable does and will clean
@@ -159,6 +168,28 @@ export class Observable<T> implements Subscribable<T> {
    *     console.log('Adding: ' + value);
    *     sum = sum + value;
    *   },
+   *   (error) => console.error(error),
+   *   () => console.log('Sum equals: ' + sum)
+   * );
+   *
+   * // Logs:
+   * // "Adding: 1"
+   * // "Adding: 2"
+   * // "Adding: 3"
+   * // "Sum equals: 6"
+   * ```
+   *
+   * ### Subscribe with functions (deprecated)
+   * ```ts
+   * import { of } from 'rxjs'
+   *
+   * let sum = 0;
+   *
+   * of(1, 2, 3).subscribe(
+   *   value => {
+   *     console.log('Adding: ' + value);
+   *     sum = sum + value;
+   *   },
    *   undefined,
    *   () => console.log('Sum equals: ' + sum)
    * );
@@ -174,14 +205,15 @@ export class Observable<T> implements Subscribable<T> {
    * ```ts
    * import { interval } from 'rxjs';
    *
-   * const subscription = interval(1000).subscribe(
-   *   num => console.log(num),
-   *   undefined,
-   *   () => {
+   * const subscription = interval(1000).subscribe({
+   *   next(num) {
+   *     console.log(num)
+   *   },
+   *   complete() {
    *     // Will not be called, even when cancelling subscription.
    *     console.log('completed!');
    *   }
-   * );
+   * });
    *
    * setTimeout(() => {
    *   subscription.unsubscribe();
@@ -198,9 +230,9 @@ export class Observable<T> implements Subscribable<T> {
    *  or the first of three possible handlers, which is the handler for each value emitted from the subscribed
    *  Observable.
    * @param {Function} error (optional) A handler for a terminal event resulting from an error. If no error handler is provided,
-   *  the error will be thrown as unhandled.
+   *  the error will be asynchronously thrown as unhandled.
    * @param {Function} complete (optional) A handler for a terminal event resulting from successful completion.
-   * @return {ISubscription} a subscription reference to the registered handlers
+   * @return {Subscription} a subscription reference to the registered handlers
    * @method subscribe
    */
   subscribe(observerOrNext?: PartialObserver<T> | ((value: T) => void) | null,