Merge pull request #229 from JakeWharton/jw/da-docs

Document items which are mutable and not safe to delay usage of.

rxbinding/src/main/java/com/jakewharton/rxbinding/view/RxView.java

@@ -165,6 +165,12 @@ public static Observable<Void> globalLayouts(@NonNull View view) {
   /**
    * Create an observable of hover events for {@code view}.
    * <p>
+   * <em>Warning:</em> Values emitted by this observable are <b>mutable</b> and part of a shared
+   * object pool and thus are <b>not safe</b> to cache or delay reading (such as by observing
+   * on a different thread). If you want to cache or delay reading the items emitted then you must
+   * map values through a function which calls {@link MotionEvent#obtain(MotionEvent)} or
+   * {@link MotionEvent#obtainNoHistory(MotionEvent)} to create a copy.
+   * <p>
    * <em>Warning:</em> The created observable keeps a strong reference to {@code view}. Unsubscribe
    * to free this reference.
    * <p>
@@ -180,6 +186,12 @@ public static Observable<MotionEvent> hovers(@NonNull View view) {
   /**
    * Create an observable of hover events for {@code view}.
    * <p>
+   * <em>Warning:</em> Values emitted by this observable are <b>mutable</b> and part of a shared
+   * object pool and thus are <b>not safe</b> to cache or delay reading (such as by observing
+   * on a different thread). If you want to cache or delay reading the items emitted then you must
+   * map values through a function which calls {@link MotionEvent#obtain(MotionEvent)} or
+   * {@link MotionEvent#obtainNoHistory(MotionEvent)} to create a copy.
+   * <p>
    * <em>Warning:</em> The created observable keeps a strong reference to {@code view}. Unsubscribe
    * to free this reference.
    * <p>
@@ -307,6 +319,12 @@ public static Observable<Integer> systemUiVisibilityChanges(@NonNull View view)
   /**
    * Create an observable of touch events for {@code view}.
    * <p>
+   * <em>Warning:</em> Values emitted by this observable are <b>mutable</b> and part of a shared
+   * object pool and thus are <b>not safe</b> to cache or delay reading (such as by observing
+   * on a different thread). If you want to cache or delay reading the items emitted then you must
+   * map values through a function which calls {@link MotionEvent#obtain(MotionEvent)} or
+   * {@link MotionEvent#obtainNoHistory(MotionEvent)} to create a copy.
+   * <p>
    * <em>Warning:</em> The created observable keeps a strong reference to {@code view}. Unsubscribe
    * to free this reference.
    * <p>
@@ -322,6 +340,12 @@ public static Observable<MotionEvent> touches(@NonNull View view) {
   /**
    * Create an observable of touch events for {@code view}.
    * <p>
+   * <em>Warning:</em> Values emitted by this observable are <b>mutable</b> and part of a shared
+   * object pool and thus are <b>not safe</b> to cache or delay reading (such as by observing
+   * on a different thread). If you want to cache or delay reading the items emitted then you must
+   * map values through a function which calls {@link MotionEvent#obtain(MotionEvent)} or
+   * {@link MotionEvent#obtainNoHistory(MotionEvent)} to create a copy.
+   * <p>
    * <em>Warning:</em> The created observable keeps a strong reference to {@code view}. Unsubscribe
    * to free this reference.
    * <p>

rxbinding/src/main/java/com/jakewharton/rxbinding/widget/RxTextView.java

@@ -90,6 +90,12 @@ public static Observable<TextViewEditorActionEvent> editorActionEvents(@NonNull
   /**
    * Create an observable of character sequences for text changes on {@code view}.
    * <p>
+   * <em>Warning:</em> Values emitted by this observable are <b>mutable</b> and owned by the host
+   * {@code TextView} and thus are <b>not safe</b> to cache or delay reading (such as by observing
+   * on a different thread). If you want to cache or delay reading the items emitted then you must
+   * map values through a function which calls {@link String#valueOf} or
+   * {@link CharSequence#toString() .toString()} to create a copy.
+   * <p>
    * <em>Warning:</em> The created observable keeps a strong reference to {@code view}. Unsubscribe
    * to free this reference.
    * <p>
@@ -104,6 +110,12 @@ public static Observable<CharSequence> textChanges(@NonNull TextView view) {
   /**
    * Create an observable of text change events for {@code view}.
    * <p>
+   * <em>Warning:</em> Values emitted by this observable contain a <b>mutable</b>
+   * {@link CharSequence} owned by the host {@code TextView} and thus are <b>not safe</b> to cache
+   * or delay reading (such as by observing on a different thread). If you want to cache or delay
+   * reading the items emitted then you must map values through a function which calls
+   * {@link String#valueOf} or {@link CharSequence#toString() .toString()} to create a copy.
+   * <p>
    * <em>Warning:</em> The created observable keeps a strong reference to {@code view}. Unsubscribe
    * to free this reference.
    * <p>