/*
 * Copyright 2020 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.android.gnd.rx.annotations;

import static java.lang.annotation.ElementType.TYPE_USE;

import java.lang.annotation.Documented;
import java.lang.annotation.Target;

/**
 * Denotes a cold observable. Unlike {@link Hot} observables, cold observables have side effects
 * when subscribed to. Typically, this includes the creation of a new producer on each subscription.
 * This interpretation has several consequences:
 *
 * <ul>
 *   <li>Cold observables are "lazy", since no actual work is done before the producer is created on
 *       subscription.
 *   <li>Items are only pushed to the stream when observers subscribe; as such, no items can be
 *       missed as the result of subscribing "too late".
 *   <li>The results generated by any two producers may differ, so observers are not guaranteed to
 *       receive the same sequence of items. As such, cold observables are not suitable for sharing
 *       the same sequence with multiple observers (<i>multicasting</i>).
 * </ul>
 *
 * <p>Cold RxJava2 observables can be created by passing a producer that generates results to the
 * observable's <code>create()</code> method.
 *
 * <p>See ReactiveX <a href="http://reactivex.io/documentation/observable.html">Observable</a> and
 * <a href="https://github.com/ReactiveX/RxJava/blob/2.x/DESIGN.md">RxJava v2 Design</a> for
 * details.
 */
@Documented
@Target({TYPE_USE})
public @interface Cold {
  /**
   * Indicates whether or not the observable is expected to terminate (<code>finite=true</code>), or
   * whether it is expected to run indefinitely <code>finite=false</code>. Cold observables are
   * considered finite by default.
   */
  boolean finite() default true;

  /**
   * Indicates whether the whole sequence must be received for its output to be useful (stateful),
   * or whether values are independent (stateless). Stateful observables require the producer and
   * observer to maintain state, while stateless observables allow observers to use idempotent
   * <code>onNext()</code> handlers.
   */
  boolean stateful() default false;

  /**
   * Indicates whether this observable records one or more items and replays them on subscription.
   */
  boolean memoized() default false;
}

@@ -899,89 +899,8 @@
  to.
- Typically, this includes the creation of a new producer on each subscription.%0A *
  Thi
@@ -987,78 +987,76 @@
 are 
-%22
+%3Ci%3E
 lazy
-%22, since no actual work is done before the producer is created on
+%3C/i%3E: the operation responsible for producing the sequence of
 %0A * 
@@ -1065,70 +1065,49 @@
     
-subscription.%0A *   %3Cli%3EItems are only pushed to the stream whe
+items is created and executed each time a
 n ob
@@ -1112,17 +1112,16 @@
 observer
-s
  subscri
@@ -1126,142 +1126,218 @@
 ribe
-; as such, no items can be%0A *       missed as the result of subscribing %22too late%22.%0A *   %3Cli%3EThe results generated by any two producer
+s. In other words, a new%0A *       producer is created on each subscription.%0A *   %3Cli%3ESince a new producer is created and executed on each subscription, the sequence emitted may%0A *       for any two subscription
 s ma
@@ -1344,20 +1344,17 @@
 y differ
-, so
+;
  observe
@@ -1377,25 +1377,16 @@
 nteed to
-%0A *      
  receive
@@ -1386,32 +1386,41 @@
 receive the same
+%0A *      
  sequence of ite
@@ -1477,25 +1477,16 @@
  sharing
-%0A *      
  the sam
@@ -1495,16 +1495,25 @@
 sequence
+%0A *      
  with mu
@@ -1559,160 +1559,158 @@
 %0A * 
-%3C/ul%3E%0A *%0A * %3Cp%3ECold RxJava2 observables can be created by passing a producer that generates results to the%0A * observable's %3Ccode%3Ecreate()%3C/code%3E method.
+  %3Cli%3ESince items are only emitted when observers subscribe, no items can be missed as result of%0A *       an observer subscribing %22too late%22.%0A * %3C/ul%3E
 %0A *%0A

Tweak JavaDoc