[docs]: ConnectableObservable lacks documentation

Documentation Related To Component:

ConnectableObservable ConnectableObservable.ts

Please check those that apply

• typo
• [ x ] documentation doesn't exist
• [ x ] documentation needs clarification
• error(s) in example
• [ x ] needs example

Description Of The Issue

I have been using observable.publish() to get a ConnectableObservable. I have been curious about whether the Subscription returned from calling .connect() on the ConnectableObservable can be used to cancel the source observable, regardless of how many generic subscribers - attached using .subscribe() or the like - are still subscribed. My quick testing suggests that is in fact the case.

There are no comments in ConnectableObservable.ts, and the API documentation page for the class, and the wider ReactiveX documentation on this class and related operators like .publish() don't detail that there is (or may be in certain implementations) a Subscription specific to ConnectableSubscriber returned from .connect() that may have a special use:

http://reactivex.io/rxjs/class/es6/observable/ConnectableObservable.js~ConnectableObservable.html -- this is empty. http://reactivex.io/documentation/operators/publish.html http://reactivex.io/documentation/operators/connect.html

Blog posts also don't much cover unsubscribing using the return value from connect, though I did see some Java examples on SO that reflect the concept: https://stackoverflow.com/questions/47618893/rxjava-reconnection-on-connectable-observable-does-not-work https://stackoverflow.com/questions/43424964/rxjava-connectableobservable-disconnecting-and-reconnecting

Please confirm for me that calling .unsubscribe() on the Subscription from ConnectableObservable.connect() in RxJS will unsubscribe all subscribers and complete the source observable; and expand the documentation to reflect this.

---

My test:

    let $hotstream = Observable.interval(1000);
    let $connectable = $hotstream.publish();

    $connectable.subscribe((val) => console.log("A" + val));
    $connectable.subscribe((val) => console.log("B" + val));

    let subscription = $connectable.connect();

    setTimeout(() => {
      subscription.unsubscribe()
    }, 2995); // should cut off before the 3rd interval at 3 seconds.

Output:

A0
B0
A1
B1