Javadoc changes to help fix #1322

Author: DavidMGross

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

@@ -4831,10 +4831,12 @@ public final Observable<T> mergeWith(Observable<? extends T> t1) {
      * Returns an Observable that emits items produced by multicasting the source Observable within a selector
      * function.
      * <p>
+     * This is largely a helper function used by RxJava for other forms of multicasting, such as
+     * {@link #publish} and {@link #publishLast}.
+     * <p>
      * {@code multicast} does not operate by default on a particular {@link Scheduler}.
      * 
      * @warn javadocs incomplete; description needs improvement
-     * @warn javadocs incomplete; marble diagram missing
      * @param subjectFactory
      *            the {@link Subject} factory
      * @warn javadocs incomplete; "subjectFactory" parameter described poorly
@@ -7772,9 +7774,6 @@ public final BlockingObservable<T> toBlocking() {
      * function once, passing it the entire list, by calling the Observable's {@code toList} method prior to
      * calling its {@link #subscribe} method.
      * <p>
-     *
-     * <!-- IS THE FOLLOWING NOTE STILL VALID? -->
-     *
      * Be careful not to use this operator on Observables that emit infinite or very large numbers of items, as
      * you do not have the option to unsubscribe.
      * <p>

rxjava-core/src/main/java/rx/observers/Observers.java

@@ -21,7 +21,7 @@
 import rx.functions.Action1;
 
 /**
- * @warn javadoc class description missing
+ * Helper methods and utilities for creating and working with {@link Observer} objects.
  */
 public class Observers {
 

rxjava-core/src/main/java/rx/observers/Subscribers.java

@@ -22,7 +22,7 @@
 import rx.functions.Action1;
 
 /**
- * @warn javadoc class description missing
+ * Helper methods and utilities for creating and working with {@link Subscriber} objects.
  */
 public final class Subscribers {
     private Subscribers() {

rxjava-core/src/main/java/rx/subjects/Subject.java

@@ -19,7 +19,7 @@
 import rx.Observer;
 
 /**
- * @warn javadoc class description missing
+ * Represents an object that is both an Observable and an Observer.
  */
 public abstract class Subject<T, R> extends Observable<R> implements Observer<T> {
     protected Subject(OnSubscribe<R> onSubscribe) {

rxjava-core/src/main/java/rx/subscriptions/MultipleAssignmentSubscription.java

@@ -72,9 +72,11 @@ public void unsubscribe() {
     }
 
     /**
-     * @warn javadoc missing
-     * @param s
-     * @throws IllegalArgumentException
+     * Sets the underlying subscription. If the {@code MultipleAssignmentSubscription} is already unsubscribed,
+     * setting a new subscription causes the new subscription to also be immediately unsubscribed.
+     *
+     * @param s the {@link Subscription} to set
+     * @throws IllegalArgumentException if {@code s} is {@code null}
      */
     public void set(Subscription s) {
         if (s == null) {
@@ -94,8 +96,9 @@ public void set(Subscription s) {
     }
 
     /**
-     * @warn javadoc missing
-     * @return
+     * Gets the underlying subscription.
+     *
+     * @return the {@link Subscription} that underlies the {@code MultipleAssignmentSubscription}
      */
     public Subscription get() {
         return state.subscription;