Clarify docs for Animator.isStarted()

Behavior is different than spec'd for one-shot animators, clarified
docs to reflect that.

Issue #21087798 better docs for isStarted()

Change-Id: I499a5d52cf02ef715acb6ae0635ede4328c93de8

1 files changed, 9 insertions, 5 deletions

diff --git a/core/java/android/animation/Animator.java b/core/java/android/animation/Animator.java
index da48709..aa1be9a 100644
--- a/core/java/android/animation/Animator.java
+++ b/core/java/android/animation/Animator.java
@@ -211,11 +211,15 @@ public abstract class Animator implements Cloneable {
     public abstract boolean isRunning();
 
     /**
-     * Returns whether this Animator has been started and not yet ended. This state is a superset
-     * of the state of {@link #isRunning()}, because an Animator with a nonzero
-     * {@link #getStartDelay() startDelay} will return true for {@link #isStarted()} during the
-     * delay phase, whereas {@link #isRunning()} will return true only after the delay phase
-     * is complete.
+     * Returns whether this Animator has been started and not yet ended. For reusable
+     * Animators (which most Animators are, apart from the one-shot animator produced by
+     * {@link android.view.ViewAnimationUtils#createCircularReveal(
+     * android.view.View, int, int, float, float) createCircularReveal()}),
+     * this state is a superset of {@link #isRunning()}, because an Animator with a
+     * nonzero {@link #getStartDelay() startDelay} will return true for {@link #isStarted()} during
+     * the delay phase, whereas {@link #isRunning()} will return true only after the delay phase
+     * is complete. Non-reusable animators will always return true after they have been
+     * started, because they cannot return to a non-started state.
      *
      * @return Whether the Animator has been started and not yet ended.
      */