add javadocs to describe SerializedSubject class

(also correct error in javadoc comments for OperatorDoOnSubscribe, for what it's worth)

Author: DavidMGross

src/main/java/rx/internal/operators/OperatorDoOnSubscribe.java

@@ -28,7 +28,7 @@ public class OperatorDoOnSubscribe<T> implements Operator<T, T> {
 
     /**
      * Constructs an instance of the operator with the callback that gets invoked when the modified Observable is subscribed
-     * @param unsubscribe The action that gets invoked when the modified {@link rx.Observable} is subscribed
+     * @param subscribe the action that gets invoked when the modified {@link rx.Observable} is subscribed
      */
     public OperatorDoOnSubscribe(Action0 subscribe) {
         this.subscribe = subscribe;

src/main/java/rx/subjects/SerializedSubject.java

@@ -18,6 +18,20 @@
 import rx.Subscriber;
 import rx.observers.SerializedObserver;
 
+/**
+ * Wraps a {@link Subject} so that it is safe to call its various {@code on} methods from different threads.
+ * <p>
+ * When you use an ordinary {@link Subject} as a {@link Subscriber}, you must take care not to call its
+ * {@link Subscriber#onNext} method (or its other {@code on} methods) from multiple threads, as this could lead
+ * to non-serialized calls, which violates the Observable contract and creates an ambiguity in the resulting
+ * Subject.
+ * <p>
+ * To protect a {@code Subject} from this danger, you can convert it into a {@code SerializedSubject} with code
+ * like the following:
+ * <p><pre>{@code
+ * mySafeSubject = new SerializedSubject( myUnsafeSubject );
+ * }</pre>
+ */
 public class SerializedSubject<T, R> extends Subject<T, R> {
     private final SerializedObserver<T> observer;