/*
 * 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
 *
 * http://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.j2objc.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * PLEASE READ THIS DOCUMENTATION BEFORE USING THIS ANNOTATION!
 * Note the criteria listed below which cannot be enforced by static analysis in
 * j2objc. Prefer using {@link Weak} over @RetainedWith if possible.
 *
 * Indicates that the annotated field (child) forms a direct reference cycle
 * with the referring object (parent). Adding this annotation informs J2ObjC of
 * the reference cycle between the pair of objects allowing both objects to be
 * deallocated once there are no external references to either object.
 *
 * {@literal @}RetainedWith can be applied when a parent object pairs itself
 * with a child object and cannot fully manage the child's lifecycle, usually
 * because the child is returned to the caller. It can also be applied when the
 * child has the same class as the parent, for example on an inverse field of an
 * invertible collection type.
 *
 * {@literal @}RetainedWith can only be applied where there is a two-object pair
 * with a cycle created by one reference from each object. Note: the two
 * references can be from the same declared field. When the references are from
 * different fields only one field should be given a @RetainedWith annotation,
 * and the {@literal @}RetainedWith field should point from parent to child.
 *
 * When applied carefully in the right circumstance this annotation is very
 * useful in preventing leaks from certain Java collection types without needing
 * to alter their behavior.
 *
 * The following criteria must be adhered to otherwise behavior will be
 * undefined:
 * - The child object must not reassign any references back to the parent
 *   object. Preferably references from child to parent are declared final.
 * - The child object must not contain any {@link Weak} references back to the
 *   parent object.
 * - The child object must not be available to other threads at the time of
 *   assignment. (Normally, the cycle is created upon construction of the child)
 *
 * @author Keith Stanger
 */
@Target({ ElementType.FIELD })
@Retention(RetentionPolicy.CLASS)
public @interface RetainedWith {
}

@@ -824,17 +824,23 @@
 TION!%0A *
- 
+%0A * %3Cp%3E
 Note the
@@ -909,14 +909,14 @@
 ysis
- in
 %0A *
+ in
  j2o
@@ -984,16 +984,19 @@
 .%0A *%0A * 
+%3Cp%3E
 Indicate
@@ -1289,32 +1289,35 @@
 r object.%0A *%0A * 
+%3Cp%3E
 %7B@literal @%7DReta
@@ -1650,16 +1650,19 @@
 .%0A *%0A * 
+%3Cp%3E
 %7B@litera
@@ -1729,16 +1729,16 @@
 ject
+%0A *
  pair
-%0A *
  wit
@@ -2046,16 +2046,19 @@
 .%0A *%0A * 
+%3Cp%3E
 When app
@@ -2237,16 +2237,19 @@
 .%0A *%0A * 
+%3Cp%3E
 The foll
@@ -2322,25 +2322,36 @@
 defined:%0A * 
--
+%3Cul%3E%0A * %3Cli%3E
  The child o
@@ -2483,25 +2483,28 @@
 d final.%0A * 
--
+%3Cli%3E
  The child o
@@ -2589,17 +2589,20 @@
 ect.%0A * 
--
+%3Cli%3E
  The chi
@@ -2746,16 +2746,25 @@
  child)%0A
+ * %3C/ul%3E%0A
  *%0A * @a

Update RetainedWith javadoc.