Diagrams and some new docs for Observable subclasses

Some marble or marblish diagrams and a bit of new documentation for the
BlockingObservable and ConnectableObservable subclasses.

Author: DavidMGross

rxjava-core/src/main/java/rx/observables/BlockingObservable.java

@@ -32,6 +32,13 @@
  * Extension of {@link Observable} that provides blocking operators.
  * <p>
  * Constructud via {@link #from(Observable)} or {@link Observable#toBlockingObservable()}
+ * <p>
+ * The documentation for this interface makes use of a form of marble diagram that has been
+ * modified to illustrate blocking operators. The following legend explains marble diagrams:
+ * <p>
+ * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/legend.png">
+ * <p>
+ * For more information see the <a href="https://github.com/Netflix/RxJava/wiki/Observable">RxJava Wiki</a>
  * 
  * @param <T>
  */
@@ -49,6 +56,8 @@ public Subscription call(Observer<T> observer) {
 
     /**
      * Returns an iterator that iterates all values of the observable.
+     * <p>
+     * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.toIterator.png">
      * 
      * @param source
      *            an observable sequence to get an iterator for.
@@ -62,6 +71,8 @@ public static <T> Iterator<T> toIterator(Observable<T> source) {
 
     /**
      * Returns the last element of an observable sequence with a specified source.
+     * <p>
+     * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.last.png">
      * 
      * @param source
      *            the source Observable
@@ -156,6 +167,8 @@ public Boolean call(T args) {
 
     /**
      * Samples the most recent value in an observable sequence.
+     * <p>
+     * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.mostRecent.png">
      * 
      * @param source
      *            the source observable sequence.
@@ -171,6 +184,8 @@ public static <T> Iterable<T> mostRecent(Observable<T> source, T initialValue) {
 
     /**
      * Samples the next value (blocking without buffering) from in an observable sequence.
+     * <p>
+     * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.next.png">
      * 
      * @param items
      *            the source observable sequence.
@@ -203,6 +218,8 @@ private static <T> T _singleOrDefault(BlockingObservable<T> source, boolean hasD
 
     /**
      * Returns the only element of an observable sequence and throws an exception if there is not exactly one element in the observable sequence.
+     * <p>
+     * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.single.png">
      * 
      * @param source
      *            the source Observable
@@ -302,6 +319,8 @@ public static <T> Future<T> toFuture(final Observable<T> source) {
 
     /**
      * Converts an observable sequence to an Iterable.
+     * <p>
+     * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.toIterable.png">
      * 
      * @param source
      *            the source Observable
@@ -331,6 +350,8 @@ private Subscription protectivelyWrapAndSubscribe(Observer<T> o) {
      * NOTE: This will block even if the Observable is asynchronous.
      * <p>
      * This is similar to {@link #subscribe(Observer)} but blocks. Because it blocks it does not need the {@link Observer#onCompleted()} or {@link Observer#onError(Exception)} methods.
+     * <p>
+     * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.forEach.png">
      * 
      * @param onNext
      *            {@link Action1}
@@ -395,6 +416,8 @@ public void onNext(T args) {
      * NOTE: This will block even if the Observable is asynchronous.
      * <p>
      * This is similar to {@link #subscribe(Observer)} but blocks. Because it blocks it does not need the {@link Observer#onCompleted()} or {@link Observer#onError(Exception)} methods.
+     * <p>
+     * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.forEach.png">
      * 
      * @param o
      *            onNext {@link Action1 action}
@@ -426,6 +449,8 @@ public void call(Object args) {
 
     /**
      * Returns an iterator that iterates all values of the observable.
+     * <p>
+     * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.getIterator.png">
      * 
      * @return the iterator that could be used to iterate over the elements of the observable.
      */
@@ -435,6 +460,8 @@ public Iterator<T> getIterator() {
 
     /**
      * Returns the last element of an observable sequence with a specified source.
+     * <p>
+     * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.last.png">
      * 
      * @return the last element in the observable sequence.
      */
@@ -527,6 +554,8 @@ public T lastOrDefault(T defaultValue, Object predicate) {
 
     /**
      * Samples the most recent value in an observable sequence.
+     * <p>
+     * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.mostRecent.png">
      * 
      * @param initialValue
      *            the initial value that will be yielded by the enumerable sequence if no element has been sampled yet.
@@ -538,6 +567,8 @@ public Iterable<T> mostRecent(T initialValue) {
 
     /**
      * Samples the next value (blocking without buffering) from in an observable sequence.
+     * <p>
+     * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.next.png">
      * 
      * @return iterable that blocks upon each iteration until the next element in the observable source sequence becomes available.
      */
@@ -547,6 +578,8 @@ public Iterable<T> next() {
 
     /**
      * Returns the only element of an observable sequence and throws an exception if there is not exactly one element in the observable sequence.
+     * <p>
+     * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.single.png">
      * 
      * @return The single element in the observable sequence.
      */
@@ -642,6 +675,8 @@ public Future<T> toFuture() {
 
     /**
      * Converts an observable sequence to an Iterable.
+     * <p>
+     * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/B.toIterable.png">
      * 
      * @return Observable converted to Iterable.
      */

rxjava-core/src/main/java/rx/observables/ConnectableObservable.java

@@ -20,12 +20,29 @@
 import rx.Subscription;
 import rx.util.functions.Func1;
 
+/**
+ * A Connectable Observable resembles an ordinary Observable, except that it does not begin
+ * emitting a sequence of values when it is subscribed to, but only when its connect() method is
+ * called. In this way you can wait for all intended observers to subscribe to the Observable
+ * before the Observable begins emitting values.
+ * <p>
+ * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/publishConnect.png">
+ * <p>
+ * For more information see the <a href="https://github.com/Netflix/RxJava/wiki/Observable">RxJava Wiki</a>
+ *
+ * @param <T>
+ */
+
 public abstract class ConnectableObservable<T> extends Observable<T> {
 
     protected ConnectableObservable(Func1<Observer<T>, Subscription> onSubscribe) {
         super(onSubscribe);
     }
 
+    /**
+     * Call a Connectable Observable's connect() method to instruct it to begin emitting the
+     * objects from its underlying Observable to its subscribing observers. 
+     */
     public abstract Subscription connect();
 
 }