javadoc improvements:

* diagrams for skip(t), single(), take(t), skipLast(t)
* minor corrections, reformatting of javadoc comments

Author: DavidMGross

rxjava-core/src/main/java/rx/Observable.java

@@ -352,6 +352,7 @@ public void onNext(T args) {
      * 
      * @param onNext
      * @return 
+     * @see <a href="https://github.com/Netflix/RxJava/wiki/Observable#onnext-oncompleted-and-onerror">RxJava Wiki: onNext, onCompleted, and onError</a>
      */
     public Subscription subscribe(final Action1<? super T> onNext) {
         if (onNext == null) {
@@ -391,6 +392,7 @@ public void onNext(T args) {
      * @param onNext
      * @param scheduler
      * @return
+     * @see <a href="https://github.com/Netflix/RxJava/wiki/Observable#onnext-oncompleted-and-onerror">RxJava Wiki: onNext, onCompleted, and onError</a>
      */
     public Subscription subscribe(final Action1<? super T> onNext, Scheduler scheduler) {
         return subscribeOn(scheduler).subscribe(onNext);
@@ -403,6 +405,7 @@ public Subscription subscribe(final Action1<? super T> onNext, Scheduler schedul
      * @param onNext
      * @param onError
      * @return
+     * @see <a href="https://github.com/Netflix/RxJava/wiki/Observable#onnext-oncompleted-and-onerror">RxJava Wiki: onNext, onCompleted, and onError</a>
      */
     public Subscription subscribe(final Action1<? super T> onNext, final Action1<Throwable> onError) {
         if (onNext == null) {
@@ -447,6 +450,7 @@ public void onNext(T args) {
      * @param onError
      * @param scheduler
      * @return
+     * @see <a href="https://github.com/Netflix/RxJava/wiki/Observable#onnext-oncompleted-and-onerror">RxJava Wiki: onNext, onCompleted, and onError</a>
      */
     public Subscription subscribe(final Action1<? super T> onNext, final Action1<Throwable> onError, Scheduler scheduler) {
         return subscribeOn(scheduler).subscribe(onNext, onError);
@@ -460,6 +464,7 @@ public Subscription subscribe(final Action1<? super T> onNext, final Action1<Thr
      * @param onError
      * @param onComplete
      * @return
+     * @see <a href="https://github.com/Netflix/RxJava/wiki/Observable#onnext-oncompleted-and-onerror">RxJava Wiki: onNext, onCompleted, and onError</a>
      */
     public Subscription subscribe(final Action1<? super T> onNext, final Action1<Throwable> onError, final Action0 onComplete) {
         if (onNext == null) {
@@ -507,6 +512,7 @@ public void onNext(T args) {
      * @param onComplete
      * @param scheduler
      * @return
+     * @see <a href="https://github.com/Netflix/RxJava/wiki/Observable#onnext-oncompleted-and-onerror">RxJava Wiki: onNext, onCompleted, and onError</a>
      */
     public Subscription subscribe(final Action1<? super T> onNext, final Action1<Throwable> onError, final Action0 onComplete, Scheduler scheduler) {
         return subscribeOn(scheduler).subscribe(onNext, onError, onComplete);
@@ -519,7 +525,7 @@ public Subscription subscribe(final Action1<? super T> onNext, final Action1<Thr
      public Observable<T> asObservable() {
          return create(new OperationAsObservable<T>(this));
      }
-    
+
     /**
      * Returns a {@link ConnectableObservable} that upon connection causes the
      * source Observable to push results into the specified subject.
@@ -641,6 +647,7 @@ public Subscription onSubscribe(Observer<? super T> observer) {
      * @return an Observable that, when an {@link Observer} subscribes to it,
      *         will execute the given function
      * @see <a href="https://github.com/Netflix/RxJava/wiki/Creating-Observables#create">RxJava Wiki: create()</a>
+     * @see <a href="http://msdn.microsoft.com/en-us/library/system.reactive.linq.observable.create.aspx">MSDN: Observable.Create</a>
      */
     public static <T> Observable<T> create(OnSubscribeFunc<T> func) {
         return new Observable<T>(func);
@@ -1074,7 +1081,7 @@ public static <T> Observable<T> from(T t1, T t2, T t3, T t4, T t5, T t6, T t7, T
      * @param count the number of sequential Integers to generate
      * @return an Observable that emits a range of sequential Integers
      * @see <a href="https://github.com/Netflix/RxJava/wiki/Creating-Observables#range">RxJava Wiki: range()</a>
-     * @see MSDN: <a href="http://msdn.microsoft.com/en-us/library/hh229460.aspx">Observable.Range Method (Int32, Int32)</a>
+     * @see <a href="http://msdn.microsoft.com/en-us/library/hh229460.aspx">MSDN: Observable.Range</a>
      */
     public static Observable<Integer> range(int start, int count) {
         return from(Range.createWithCount(start, count));
@@ -1091,7 +1098,7 @@ public static Observable<Integer> range(int start, int count) {
      * @param scheduler the scheduler to run the generator loop on
      * @return an Observable that emits a range of sequential Integers
      * @see <a href="https://github.com/Netflix/RxJava/wiki/Creating-Observables#range">RxJava Wiki: range()</a>
-     * @see MSDN: <a href="http://msdn.microsoft.com/en-us/library/hh211896.aspx">Observable.Range Method (Int32, Int32, IScheduler)</a>
+     * @see <a href="http://msdn.microsoft.com/en-us/library/hh211896.aspx">MSDN: Observable.Range</a>
      */
     public static Observable<Integer> range(int start, int count, Scheduler scheduler) {
         return from(Range.createWithCount(start, count), scheduler);
@@ -5382,29 +5389,30 @@ public Observable<T> skip(int num) {
 
     /**
      * Create an Observable that skips values before the given time ellapses.
+     * <p>
+     * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/skip.t.png">
      * 
-     * @param time
-     *            the length of the time window
-     * @param unit
-     *            the time unit
+     * @param time the length of the time window
+     * @param unit the time unit
      * @return an Observable that skips values before the given time ellapses
+     * @see <a href="https://github.com/Netflix/RxJava/wiki/Filtering-Observables#skip">RxJava Wiki: skip()</a>
      */
     public Observable<T> skip(long time, TimeUnit unit) {
         return skip(time, unit, Schedulers.threadPoolForComputation());
     }
 
     /**
-     * Create an Observable that skips values before the given time
-     * elapses while waiting on the given scheduler.
+     * Create an Observable that skips values before the given time elapses
+     * while waiting on the given scheduler.
+     * <p>
+     * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/skip.ts.png">
      * 
-     * @param time
-     *            the length of the time window
-     * @param unit
-     *            the time unit
-     * @param scheduler
-     *            the scheduler where the timed wait happens
-     * @return an Observable that skips values before the given time
-     *         elapses while waiting on the given scheduler
+     * @param time the length of the time window
+     * @param unit the time unit
+     * @param scheduler the scheduler where the timed wait happens
+     * @return an Observable that skips values before the given time elapses
+     *         while waiting on the given scheduler
+     * @see <a href="https://github.com/Netflix/RxJava/wiki/Filtering-Observables#skip">RxJava Wiki: skip()</a>
      */
     public Observable<T> skip(long time, TimeUnit unit, Scheduler scheduler) {
         return create(new OperationSkip.SkipTimed<T>(this, time, unit, scheduler));
@@ -5414,12 +5422,13 @@ public Observable<T> skip(long time, TimeUnit unit, Scheduler scheduler) {
      * If the Observable completes after emitting a single item, return an
      * Observable containing that item. If it emits more than one item or no
      * item, throw an IllegalArgumentException.
+     * <p>
+     * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/single.png">
      * 
      * @return an Observable that emits the single item emitted by the source
      *         Observable that matches the predicate
-     * @throws IllegalArgumentException
-     *             if the source emits more than one item
-     *             or no items
+     * @throws IllegalArgumentException if the source emits more than one item
+     *                                  or no items
      * @see <a href="https://github.com/Netflix/RxJava/wiki/Observable-Utility-Operators#single-and-singleordefault">RxJava Wiki: single()</a>
      * @see MSDN: <code>Observable.singleAsync()</code>
      */
@@ -5605,29 +5614,38 @@ public Observable<T> take(final int num) {
     }
 
     /**
-      * Create an Observable that takes the emitted values of the source
-      * Observable before the time runs out.
-      * @param time the length of the time window
-      * @param unit the time unit
-      * @return an Observable that takes the emitted values of the source
-      *         Observable before the time runs out.
-      */
-     public Observable<T> take(long time, TimeUnit unit) {
-         return take(time, unit, Schedulers.threadPoolForComputation());
-     }
+     * Create an Observable that emits the emitted items from the source
+     * Observable before the time runs out.
+     * <p>
+     * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/take.t.png">
+     * 
+     * @param time the length of the time window
+     * @param unit the time unit
+     * @return an Observable that emits the emitted items from the source
+     *         Observable before the time runs out
+     * @see <a href="https://github.com/Netflix/RxJava/wiki/Filtering-Observables#take">RxJava Wiki: take()</a>
+     */
+    public Observable<T> take(long time, TimeUnit unit) {
+        return take(time, unit, Schedulers.threadPoolForComputation());
+    }
 
-     /**
-      * Create an Observable that takes the emitted values of the source
-      * Observable before the time runs out, waiting on the given scheduler.
-      * @param time the length of the time window
-      * @param unit the time unit
-      * @param scheduler the scheduler used for time source
-      * @return an Observable that takes the emitted values of the source
-      *         Observable before the time runs out, waiting on the given scheduler.
-      */
-     public Observable<T> take(long time, TimeUnit unit, Scheduler scheduler) {
-         return create(new OperationTake.TakeTimed<T>(this, time, unit, scheduler));
-     }
+    /**
+     * Create an Observable that emits the emitted items from the source
+     * Observable before the time runs out, waiting on the given scheduler.
+     * <p>
+     * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/take.ts.png">
+     * 
+     * @param time the length of the time window
+     * @param unit the time unit
+     * @param scheduler the scheduler used for time source
+     * @return an Observable that emits the emitted items from the source
+     *         Observable before the time runs out, waiting on the given
+     *         scheduler
+     * @see <a href="https://github.com/Netflix/RxJava/wiki/Filtering-Observables#take">RxJava Wiki: take()</a>
+     */
+    public Observable<T> take(long time, TimeUnit unit, Scheduler scheduler) {
+        return create(new OperationTake.TakeTimed<T>(this, time, unit, scheduler));
+    }
 
     /**
      * Returns an Observable that emits items emitted by the source Observable
@@ -5972,25 +5990,35 @@ public Observable<T> skipLast(int count) {
     }
 
     /**
-     * Create an observable which skips values emitted in a time window
-     * before the source completes.
+     * Create an Observable that skips values emitted in a time window before
+     * the source completes.
+     * <p>
+     * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/skipLast.t.png">
+     *
      * @param time the length of the time window
      * @param unit the time unit
-     * @return an observable which skips values emitted in a time window
-     * before the source completes
+     * @return an Observable that skips values emitted in a time window before
+     *         the source completes
+     * @see <a href="https://github.com/Netflix/RxJava/wiki/Filtering-Observables#skiplast">RxJava Wiki: skipLast()</a>
+     * @see <a href="http://msdn.microsoft.com/en-us/library/hh211750.aspx">MSDN: Observable.SkipLast</a>
      */
     public Observable<T> skipLast(long time, TimeUnit unit) {
         return skipLast(time, unit, Schedulers.threadPoolForComputation());
     }
 
     /**
-     * Create an observable which skips values emitted in a time window
-     * before the source completes by using the given scheduler as time source.
+     * Create an Observable that skips values emitted in a time window before
+     * the source completes by using the given scheduler as time source.
+     * <p>
+     * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/skipLast.ts.png">
+     *
      * @param time the length of the time window
      * @param unit the time unit
      * @param scheduler the scheduler used for time source
-     * @return an observable which skips values emitted in a time window
-     * before the source completes by using the given scheduler as time source
+     * @return an Observable that skips values emitted in a time window before
+     *         the source completes by using the given scheduler as time source
+     * @see <a href="https://github.com/Netflix/RxJava/wiki/Filtering-Observables#skiplast">RxJava Wiki: skipLast()</a>
+     * @see <a href="http://msdn.microsoft.com/en-us/library/hh211750.aspx">MSDN: Observable.SkipLast</a>
      */
     public Observable<T> skipLast(long time, TimeUnit unit, Scheduler scheduler) {
         return create(new OperationSkipLast.SkipLastTimed<T>(this, time, unit, scheduler));
@@ -6894,8 +6922,8 @@ public void onNext(T args) { }
      * <p>
      * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/doOnNext.png">
      *
-     * @param onCompleted the action to invoke when the source Observable calls
-     *                    <code>onCompleted</code>
+     * @param onNext the action to invoke when the source Observable calls
+     *               <code>onNext</code>
      * @return the source Observable with the side-effecting behavior applied
      * @see <a href="https://github.com/Netflix/RxJava/wiki/Observable-Utility-Operators#dooneach">RxJava Wiki: doOnNext()</a>
      * @see <a href="http://msdn.microsoft.com/en-us/library/hh229804.aspx">MSDN: Observable.Do</a>
@@ -6958,7 +6986,7 @@ public void onNext(T v) {
      * For why this is being used see
      * https://github.com/Netflix/RxJava/issues/216 for discussion on
      * "Guideline 6.4: Protect calls to user code from within an operator"
-     * 
+     * <p>
      * Note: If strong reasons for not depending on package names comes up then
      * the implementation of this method can change to looking for a marker
      * interface.