/*
 * 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.ANNOTATION_TYPE;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.LOCAL_VARIABLE;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.PARAMETER;

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>Items are only pushed to the stream after an observer subscribes; no items can be missed as
 *       a result of an observer subscribing after they were emitted. Each observer receives the
 *       full sequence from the beginning.
 *   <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>). To allow multicasting,
 *       RxJava2 cold observables can be turned into hot connectable observers using the respective
 *       observable class' <code>share()</code> and <code>connect()</code> methods.
 * </ul>
 *
 * <p>Cold RxJava2 observables can be created by passing a producer that generates results to the
 * observable's <code>create()</code> method. Both {@link androidx.lifecycle.LiveData} and RxJava2
 * observables backed by cold observables are also cold by default.
 *
 * <p>See ReactiveX's <a href="https://github.com/ReactiveX/RxJava/blob/2.x/DESIGN.md">RxJava v2
 * Design</a> for more definitions.
 */
@Documented
@Target(value = {ANNOTATION_TYPE, FIELD, LOCAL_VARIABLE, METHOD, PARAMETER})
public @interface Cold {}

@@ -752,189 +752,16 @@
 ype.
-FIELD;%0Aimport static java.lang.annotation.ElementType.LOCAL_VARIABLE;%0Aimport static java.lang.annotation.ElementType.METHOD;%0Aimport static java.lang.annotation.ElementType.PARAMETER
+TYPE_USE
 ;%0A%0Ai
@@ -1111,99 +1111,99 @@
 %3Cli%3E
-Items are only pushed to the stream after an observer subscribes; no items can be missed as
+Cold observables are %22lazy%22, since no actual work is done before the producer is created on
 %0A * 
@@ -1212,137 +1212,173 @@
     
-a result of an observer subscribing after they were emitted. Each observer receives the%0A *       full sequence from the beginning
+subscription.%0A *   %3Cli%3EItems are only pushed to the stream when observers subscribe; as such, no items can be%0A *       missed as the result of subscribing %22too late%22
 .%0A *
@@ -2322,48 +2322,16 @@
 PE, 
-FIELD, LOCAL_VARIABLE, METHOD, PARAMETER
+TYPE_USE
 %7D)%0Ap

Reword JavaDoc