Merge "Document behavior of object references in Animator classes" into nyc-dev

am: faa5726

* commit 'faa572608c7d62b116d3b9c6f28bd7eaddf8dba2':
  Document behavior of object references in Animator classes

Change-Id: Ic57273c1be809c14a642993ac09e203c1fb7247b

core/java/android/animation/ObjectAnimator.java

@@ -585,6 +585,11 @@ public final class ObjectAnimator extends ValueAnimator {
      * along the way, and an ending value (these values will be distributed evenly across
      * the duration of the animation).
      *
+     * <p><strong>Note:</strong> The values are stored as references to the original
+     * objects, which means that changes to those objects after this method is called will
+     * affect the values on the animator. If the objects will be mutated externally after
+     * this method is called, callers should pass a copy of those objects instead.
+     *
      * @param target The object whose property is to be animated. This object should
      * have a public method on it called <code>setName()</code>, where <code>name</code> is
      * the value of the <code>propertyName</code> parameter.
@@ -635,6 +640,11 @@ public final class ObjectAnimator extends ValueAnimator {
      * along the way, and an ending value (these values will be distributed evenly across
      * the duration of the animation).
      *
+     * <p><strong>Note:</strong> The values are stored as references to the original
+     * objects, which means that changes to those objects after this method is called will
+     * affect the values on the animator. If the objects will be mutated externally after
+     * this method is called, callers should pass a copy of those objects instead.
+     *
      * @param target The object whose property is to be animated.
      * @param property The property being animated.
      * @param evaluator A TypeEvaluator that will be called on each animation frame to
@@ -663,6 +673,11 @@ public final class ObjectAnimator extends ValueAnimator {
      * supplied, the <code>TypeConverter</code> must be a
      * {@link android.animation.BidirectionalTypeConverter} to retrieve the current value.
      *
+     * <p><strong>Note:</strong> The values are stored as references to the original
+     * objects, which means that changes to those objects after this method is called will
+     * affect the values on the animator. If the objects will be mutated externally after
+     * this method is called, callers should pass a copy of those objects instead.
+     *
      * @param target The object whose property is to be animated.
      * @param property The property being animated.
      * @param converter Converts the animated object to the Property type.

core/java/android/animation/PropertyValuesHolder.java

@@ -388,6 +388,11 @@ public class PropertyValuesHolder implements Cloneable {
      * set of Object values. This variant also takes a TypeEvaluator because the system
      * cannot automatically interpolate between objects of unknown type.
      *
+     * <p><strong>Note:</strong> The Object values are stored as references to the original
+     * objects, which means that changes to those objects after this method is called will
+     * affect the values on the PropertyValuesHolder. If the objects will be mutated externally
+     * after this method is called, callers should pass a copy of those objects instead.
+     *
      * @param propertyName The name of the property being animated.
      * @param evaluator A TypeEvaluator that will be called on each animation frame to
      * provide the necessary interpolation between the Object values to derive the animated
@@ -433,6 +438,11 @@ public class PropertyValuesHolder implements Cloneable {
      * set of Object values. This variant also takes a TypeEvaluator because the system
      * cannot automatically interpolate between objects of unknown type.
      *
+     * <p><strong>Note:</strong> The Object values are stored as references to the original
+     * objects, which means that changes to those objects after this method is called will
+     * affect the values on the PropertyValuesHolder. If the objects will be mutated externally
+     * after this method is called, callers should pass a copy of those objects instead.
+     *
      * @param property The property being animated. Should not be null.
      * @param evaluator A TypeEvaluator that will be called on each animation frame to
      * provide the necessary interpolation between the Object values to derive the animated
@@ -458,6 +468,11 @@ public class PropertyValuesHolder implements Cloneable {
      * must be a {@link android.animation.BidirectionalTypeConverter} to retrieve the current
      * value.
      *
+     * <p><strong>Note:</strong> The Object values are stored as references to the original
+     * objects, which means that changes to those objects after this method is called will
+     * affect the values on the PropertyValuesHolder. If the objects will be mutated externally
+     * after this method is called, callers should pass a copy of those objects instead.
+     *
      * @param property The property being animated. Should not be null.
      * @param converter Converts the animated object to the Property type.
      * @param evaluator A TypeEvaluator that will be called on each animation frame to
@@ -636,7 +651,12 @@ public class PropertyValuesHolder implements Cloneable {
      * {@link ObjectAnimator}, and with a getter function
      * derived automatically from <code>propertyName</code>, since otherwise PropertyValuesHolder has
      * no way of determining what the value should be.
-     * 
+     *
+     * <p><strong>Note:</strong> The Object values are stored as references to the original
+     * objects, which means that changes to those objects after this method is called will
+     * affect the values on the PropertyValuesHolder. If the objects will be mutated externally
+     * after this method is called, callers should pass a copy of those objects instead.
+     *
      * @param values One or more values that the animation will animate between.
      */
     public void setObjectValues(Object... values) {

core/java/android/animation/ValueAnimator.java

@@ -353,6 +353,11 @@ public class ValueAnimator extends Animator implements AnimationHandler.Animatio
      * from the target object and property being animated). Therefore, there should typically
      * be two or more values.
      *
+     * <p><strong>Note:</strong> The Object values are stored as references to the original
+     * objects, which means that changes to those objects after this method is called will
+     * affect the values on the animator. If the objects will be mutated externally after
+     * this method is called, callers should pass a copy of those objects instead.
+     *
      * <p>Since ValueAnimator does not know how to animate between arbitrary Objects, this
      * factory method also takes a TypeEvaluator object that the ValueAnimator will use
      * to perform that interpolation.
@@ -434,6 +439,11 @@ public class ValueAnimator extends Animator implements AnimationHandler.Animatio
      * from the target object and property being animated). Therefore, there should typically
      * be two or more values.
      *
+     * <p><strong>Note:</strong> The Object values are stored as references to the original
+     * objects, which means that changes to those objects after this method is called will
+     * affect the values on the animator. If the objects will be mutated externally after
+     * this method is called, callers should pass a copy of those objects instead.
+     *
      * <p>If there are already multiple sets of values defined for this ValueAnimator via more
      * than one PropertyValuesHolder object, this method will set the values for the first
      * of those objects.</p>