add caveat about avoiding memory leaks when using GroupedObservables

Author: DavidMGross

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

@@ -2255,12 +2255,12 @@ public final static <T> Observable<Observable<T>> parallelMerge(Observable<Obser
     }
 
     /**
-     * Pivots a sequence of GroupedObservables emitted by an Observable so as to swap the group and and the set
-     * on which their items are grouped.
+     * Pivots a sequence of {@code GroupedObservable}s emitted by an {@code Observable} so as to swap the group
+     * and and the set on which their items are grouped.
      * <p>
      * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/pivot.png">
      *
-     * For example an Observable such as this =&gt;
+     * For example an {@code Observable} such as this =&gt;
      * 
      * {@code Observable<GroupedObservable<String, GroupedObservable<Boolean, Integer>>>}:
      * <ul>
@@ -2280,10 +2280,16 @@ public final static <T> Observable<Observable<T>> parallelMerge(Observable<Obser
      * </ul>
      * <p>
      * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/pivot.ex.png">
+     * <p>
+     * <em>Note:</em> A {@link GroupedObservable} will cache the items it is to emit until such time as it
+     * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
+     * {@code GroupedObservable}s that do not concern you. Instead, you can signal to them that they may
+     * discard their buffers by applying an operator like {@link #take}{@code (0)} to them.
      * 
      * @param groups
                  the {@link GroupedObservable} to pivot
-     * @return an Observable containing a stream of nested GroupedObservables with swapped inner-outer keys.
+     * @return an {@code Observable} containing a stream of nested {@code GroupedObservable}s with swapped
+     *         inner-outer keys.
      * @since 0.17
      */
     public static final <K1, K2, T> Observable<GroupedObservable<K2, GroupedObservable<K1, T>>> pivot(Observable<GroupedObservable<K1, GroupedObservable<K2, T>>> groups) {
@@ -4027,36 +4033,47 @@ public final void forEach(final Action1<? super T> onNext, final Action1<Throwab
     }
 
     /**
-     * Groups the items emitted by an Observable according to a specified criterion, and emits these grouped
-     * items as {@link GroupedObservable}s, one {@code GroupedObservable} per group.
+     * Groups the items emitted by an {@code Observable} according to a specified criterion, and emits these
+     * grouped items as {@link GroupedObservable}s, one {@code GroupedObservable} per group.
      * <p>
      * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/groupBy.png">
+     * <p>
+     * <em>Note:</em> A {@link GroupedObservable} will cache the items it is to emit until such time as it
+     * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
+     * {@code GroupedObservable}s that do not concern you. Instead, you can signal to them that they may
+     * discard their buffers by applying an operator like {@link #take}{@code (0)} to them.
      * 
      * @param keySelector
      *            a function that extracts the key for each item
      * @param <K>
      *            the key type
-     * @return an Observable that emits {@link GroupedObservable}s, each of which corresponds to a unique key
-     *         value and each of which emits those items from the source Observable that share that key value
+     * @return an {@code Observable} that emits {@link GroupedObservable}s, each of which corresponds to a
+     *         unique key value and each of which emits those items from the source Observable that share that
+     *         key value
      * @see <a href="https://github.com/Netflix/RxJava/wiki/Transforming-Observables#wiki-groupby-and-groupbyuntil">RxJava Wiki: groupBy</a>
      */
     public final <K> Observable<GroupedObservable<K, T>> groupBy(final Func1<? super T, ? extends K> keySelector) {
         return lift(new OperatorGroupBy<K, T>(keySelector));
     }
 
     /**
-     * Groups the items emitted by an Observable according to a specified key selector function until the
-     * duration Observable expires for the key.
+     * Groups the items emitted by an {@code Observable} according to a specified key selector function until
+     * the duration {@code Observable} expires for the key.
      * <p>
      * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/groupByUntil.png">
+     * <p>
+     * <em>Note:</em> A {@link GroupedObservable} will cache the items it is to emit until such time as it
+     * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
+     * {@code GroupedObservable}s that do not concern you. Instead, you can signal to them that they may
+     * discard their buffers by applying an operator like {@link #take}{@code (0)} to them.
      * 
      * @param keySelector
      *            a function to extract the key for each item
      * @param durationSelector
      *            a function to signal the expiration of a group
-     * @return an Observable that emits {@link GroupedObservable}s, each of which corresponds to a key value and
-     *         each of which emits all items emitted by the source Observable during that key's duration that
-     *         share that same key value
+     * @return an {@code Observable} that emits {@link GroupedObservable}s, each of which corresponds to a key
+     *         value and each of which emits all items emitted by the source {@code Observable} during that
+     *         key's duration that share that same key value
      * @see <a href="https://github.com/Netflix/RxJava/wiki/Transforming-Observables#wiki-groupby-and-groupbyuntil">RxJava Wiki: groupByUntil()</a>
      * @see <a href="http://msdn.microsoft.com/en-us/library/hh211932.aspx">MSDN: Observable.GroupByUntil</a>
      */
@@ -4065,21 +4082,26 @@ public final <TKey, TDuration> Observable<GroupedObservable<TKey, T>> groupByUnt
     }
 
     /**
-     * Groups the items emitted by an Observable (transformed by a selector) according to a specified key
-     * selector function until the duration Observable expires for the key.
+     * Groups the items emitted by an {@code Observable} (transformed by a selector) according to a specified
+     * key selector function until the duration Observable expires for the key.
      * <p>
      * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/groupByUntil.png">
+     * <p>
+     * <em>Note:</em> A {@link GroupedObservable} will cache the items it is to emit until such time as it
+     * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
+     * {@code GroupedObservable}s that do not concern you. Instead, you can signal to them that they may
+     * discard their buffers by applying an operator like {@link #take}{@code (0)} to them.
      * 
      * @param keySelector
      *            a function to extract the key for each item
      * @param valueSelector
-     *            a function to map each item emitted by the source Observable to an item emitted by one of the
-     *            resulting {@link GroupedObservable}s
+     *            a function to map each item emitted by the source {@code Observable} to an item emitted by one
+     *            of the resulting {@link GroupedObservable}s
      * @param durationSelector
      *            a function to signal the expiration of a group
-     * @return an Observable that emits {@link GroupedObservable}s, each of which corresponds to a key value and
-     *         each of which emits all items emitted by the source Observable during that key's duration that
-     *         share that same key value, transformed by the value selector
+     * @return an {@code Observable} that emits {@link GroupedObservable}s, each of which corresponds to a key
+     *         value and each of which emits all items emitted by the source {@code Observable} during that
+     *         key's duration that share that same key value, transformed by the value selector
      * @see <a href="https://github.com/Netflix/RxJava/wiki/Transforming-Observables#wiki-groupby-and-groupbyuntil">RxJava Wiki: groupByUntil()</a>
      * @see <a href="http://msdn.microsoft.com/en-us/library/hh229433.aspx">MSDN: Observable.GroupByUntil</a>
      */

rxjava-core/src/main/java/rx/observables/GroupedObservable.java

@@ -22,15 +22,19 @@
 /**
  * An {@link Observable} that has been grouped by key, the value of which can be obtained with
  * {@link #getKey()}.
- * 
- * @see Observable#groupBy(Func1)
- * @see <a href="https://github.com/Netflix/RxJava/wiki/Transforming-Observables#groupby-and-groupbyuntil">RxJava Wiki: groupBy() and groupByUntil()</a>
- * @see <a href="https://github.com/Netflix/RxJava/wiki/Transforming-Observables#pivot">RxJava Wiki: pivot()</a>
+ * <p>
+ * <em>Note:</em> A {@link GroupedObservable} will cache the items it is to emit until such time as it
+ * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
+ * {@code GroupedObservable}s that do not concern you. Instead, you can signal to them that they may
+ * discard their buffers by applying an operator like {@link Observable#take}{@code (0)} to them.
  * 
  * @param <K>
  *            the type of the key
  * @param <T>
  *            the type of the items emitted by the {@code GroupedObservable}
+ * @see Observable#groupBy(Func1)
+ * @see <a href="https://github.com/Netflix/RxJava/wiki/Transforming-Observables#groupby-and-groupbyuntil">RxJava Wiki: groupBy() and groupByUntil()</a>
+ * @see <a href="https://github.com/Netflix/RxJava/wiki/Transforming-Observables#pivot">RxJava Wiki: pivot()</a>
  */
 public class GroupedObservable<K, T> extends Observable<T> {
     private final K key;