2 files changed, 37 insertions, 12 deletions
diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index 2f67481..14e8212 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -537,9 +537,32 @@ import java.util.concurrent.CopyOnWriteArrayList;
  * themselves rather than by putting them in a separate structure.
  * </p>
  *
+ * <a name="Properties"></a>
+ * <h3>Properties</h3>
+ * <p>
+ * The View class exposes an {@link #ALPHA} property, as well as several transform-related
+ * properties, such as {@link #TRANSLATION_X} and {@link #TRANSLATION_Y}. These properties are
+ * available both in the {@link Property} form as well as in similarly-named setter/getter
+ * methods (such as {@link #setAlpha(float)} for {@link #ALPHA}). These properties can
+ * be used to set persistent state associated with these rendering-related properties on the view.
+ * The properties and methods can also be used in conjunction with
+ * {@link android.animation.Animator Animator}-based animations, described more in the
+ * <a href="#Animation">Animation</a> section.
+ * </p>
+ *
  * <a name="Animation"></a>
  * <h3>Animation</h3>
  * <p>
+ * Starting with Android 3.0, the preferred way of animating views is to use the
+ * {@link android.animation} package APIs. These {@link android.animation.Animator Animator}-based
+ * classes change actual properties of the View object, such as {@link #setAlpha(float) alpha} and
+ * {@link #setTranslationX(float) translationX}. This behavior is contrasted to that of the pre-3.0
+ * {@link android.view.animation.Animation Animation}-based classes, which instead animate only
+ * how the view is drawn on the display. In particular, the {@link ViewPropertyAnimator} class
+ * makes animating these View properties particularly easy and efficient.
+ * </p>
+ * <p>
+ * Alternatively, you can use the pre-3.0 animation classes to animate how Views are rendered.
  * You can attach an {@link Animation} object to a view using
  * {@link #setAnimation(Animation)} or
  * {@link #startAnimation(Animation)}. The animation can alter the scale,
@@ -548,10 +571,6 @@ import java.util.concurrent.CopyOnWriteArrayList;
  * subtree rooted by that node. When an animation is started, the framework will
  * take care of redrawing the appropriate views until the animation completes.
  * </p>
- * <p>
- * Starting with Android 3.0, the preferred way of animating views is to use the
- * {@link android.animation} package APIs.
- * </p>
  *
  * <a name="Security"></a>
  * <h3>Security</h3>
diff --git a/core/java/android/view/ViewPropertyAnimator.java b/core/java/android/view/ViewPropertyAnimator.java
index ec37acf..2012db2 100644
--- a/core/java/android/view/ViewPropertyAnimator.java
+++ b/core/java/android/view/ViewPropertyAnimator.java
@@ -624,14 +624,20 @@ public class ViewPropertyAnimator {
     /**
      * The View associated with this ViewPropertyAnimator will have its
      * {@link View#setLayerType(int, android.graphics.Paint) layer type} set to
-     * {@link View#LAYER_TYPE_HARDWARE} for the duration of the next animation. This state
-     * is not persistent, either on the View or on this ViewPropertyAnimator: the layer type
-     * of the View will be restored when the animation ends to what it was when this method was
-     * called, and this setting on ViewPropertyAnimator is only valid for the next animation.
-     * Note that calling this method and then independently setting the layer type of the View
-     * (by a direct call to {@link View#setLayerType(int, android.graphics.Paint)}) will result
-     * in some inconsistency, including having the layer type restored to its pre-withLayer()
-     * value when the animation ends.
+     * {@link View#LAYER_TYPE_HARDWARE} for the duration of the next animation.
+     * As stated in the documentation for {@link View#LAYER_TYPE_HARDWARE},
+     * the actual type of layer used internally depends on the runtime situation of the
+     * view. If the activity and this view are hardware-accelerated, then the layer will be
+     * accelerated as well. If the activity or the view is not accelerated, then the layer will
+     * effectively be the same as {@link View#LAYER_TYPE_SOFTWARE}.
+     *
+     * <p>This state is not persistent, either on the View or on this ViewPropertyAnimator: the
+     * layer type of the View will be restored when the animation ends to what it was when this
+     * method was called, and this setting on ViewPropertyAnimator is only valid for the next
+     * animation. Note that calling this method and then independently setting the layer type of
+     * the View (by a direct call to {@link View#setLayerType(int, android.graphics.Paint)}) will
+     * result in some inconsistency, including having the layer type restored to its pre-withLayer()
+     * value when the animation ends.</p>
      *
      * @see View#setLayerType(int, android.graphics.Paint)
      * @return This object, allowing calls to methods in this class to be chained.