javadocs: withLatestFrom diagram, @SInCE annotations, standardize on formatting and terminology, add compiler nags for missing content

Author: DavidMGross

src/main/java/rx/Observable.java

@@ -2573,25 +2573,27 @@ public final static <T, Resource> Observable<T> using(
 
     /**
      * Constructs an Observable that creates a dependent resource object which is disposed of just before 
-     * termination if <code>disposeEagerly</code> is set to true and unsubscription does not occur before termination. Otherwise
-     * resource disposal will occur on unsubscription.  Eager disposal is particularly appropriate for a synchronous observable
-     * that resuses resources. <code>disposeAction</code> will only be called once per subscription.
+     * termination if you have set {@code disposeEagerly} to {@code true} and unsubscription does not occur
+     * before termination. Otherwise resource disposal will occur on unsubscription.  Eager disposal is
+     * particularly appropriate for a synchronous Observable that resuses resources. {@code disposeAction} will
+     * only be called once per subscription.
      * <p>
      * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/using.png" alt="">
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code using} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
      * 
+     * @warn "Backpressure Support" section missing from javadoc
      * @param resourceFactory
      *            the factory function to create a resource object that depends on the Observable
      * @param observableFactory
      *            the factory function to create an Observable
      * @param disposeAction
      *            the function that will dispose of the resource
      * @param disposeEagerly
-     *            if true then disposal will happen either on unsubscription or just before emission of 
-     *            a terminal event (onComplete or onError).
+     *            if {@code true} then disposal will happen either on unsubscription or just before emission of 
+     *            a terminal event ({@code onComplete} or {@code onError}).
      * @return the Observable whose lifetime controls the lifetime of the dependent resource object
      * @see <a href="http://reactivex.io/documentation/operators/using.html">ReactiveX operators documentation: Using</a>
      * @Experimental The behavior of this can change at any time.
@@ -8805,24 +8807,24 @@ public final Observable<T> unsubscribeOn(Scheduler scheduler) {
     }
 
     /**
-     * Merges the specified observable sequence into this Observable sequence by using the resultSelector 
-     * function only when the source observable sequence (this instance) produces an element.
-     * <code><pre>
-     * ----A-------B------C----->  o1
-     *
-     * --0----1-2----3-4-------->  o2
-     *
-     *     |       |      |
-     *     V       V      V
+     * Merges the specified Observable into this Observable sequence by using the {@code resultSelector}
+     * function only when the source Observable (this instance) emits an item.
+     * <p>
+     * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/withLatestFrom.png" alt="">
      *
-     *   (A,0)   (B,2)  (C,4)
-     * </pre></code>
-     * @param other the other observable sequence
-     * @param resultSelector the function to call when this Observable emits an element and the other
-     *            observable sequence has already emitted a value.
-     * @return an Observable that merges the specified observable sequence into this Observable sequence 
-     *            by using the resultSelector function only when the source observable sequence 
-     *            (this instance) produces an element
+     * @warn "Backpressure Support" section missing from javadoc
+     * @warn "Scheduler" section missing from javadoc
+     * @param other
+     *            the other Observable
+     * @param resultSelector
+     *            the function to call when this Observable emits an item and the other Observable has already
+     *            emitted an item, to generate the item to be emitted by the resulting Observable
+     * @return an Observable that merges the specified Observable into this Observable by using the
+     *         {@code resultSelector} function only when the source Observable sequence (this instance) emits an
+     *         item
+     * @Experimental The behavior of this can change at any time.
+     * @since (if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)
+     * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
      */
     @Experimental
     public final <U, R> Observable<R> withLatestFrom(Observable<? extends U> other, Func2<? super T, ? super U, ? extends R> resultSelector) {

src/main/java/rx/observers/SerializedSubscriber.java

@@ -39,12 +39,16 @@ public class SerializedSubscriber<T> extends Subscriber<T> {
     public SerializedSubscriber(Subscriber<? super T> s) {
         this(s, true);
     }
+
     /**
      * Constructor for wrapping and serializing a subscriber optionally sharing the same underlying subscription
      * list.
-     * @param s the subscriber to wrap and serialize
-     * @param shareSubscriptions if {@code true}, the same subscription list is shared between this
-     * subscriber and {@code s}.
+     *
+     * @param s
+     *          the subscriber to wrap and serialize
+     * @param shareSubscriptions
+     *          if {@code true}, the same subscription list is shared between this subscriber and {@code s}.
+     * @since 1.0.7
      */
     public SerializedSubscriber(Subscriber<? super T> s, boolean shareSubscriptions) {
         super(s, shareSubscriptions);

src/main/java/rx/subscriptions/CompositeSubscription.java

@@ -150,9 +150,12 @@ private static void unsubscribeFromAll(Collection<Subscription> subscriptions) {
         }
         Exceptions.throwIfAny(es);
     }
+
     /**
      * Returns true if this composite is not unsubscribed and contains subscriptions.
+     *
      * @return {@code true} if this composite is not unsubscribed and contains subscriptions.
+     * @since 1.0.7
      */
     public boolean hasSubscriptions() {
         if (!unsubscribed) {