1 files changed, 49 insertions, 19 deletions
diff --git a/src/jogl/classes/javax/media/opengl/GLAnimatorControl.java b/src/jogl/classes/javax/media/opengl/GLAnimatorControl.java
index 83e9e22c4..827145654 100644
--- a/src/jogl/classes/javax/media/opengl/GLAnimatorControl.java
+++ b/src/jogl/classes/javax/media/opengl/GLAnimatorControl.java
@@ -29,24 +29,24 @@
 package javax.media.opengl;
 
 /**
- * An animator control interface, 
+ * An animator control interface,
  * which implementation may drive a {@link javax.media.opengl.GLAutoDrawable} animation.
  */
 public interface GLAnimatorControl extends FPSCounter {
 
     /**
-     * Indicates whether this animator is running, ie. has been started and not stopped.
+     * Indicates whether this animator has been {@link #start() started}.
      *
      * @see #start()
      * @see #stop()
+     * @see #isPaused()
      * @see #pause()
      * @see #resume()
      */
     boolean isStarted();
 
     /**
-     * Indicates whether this animator is running and animating,<br>
-     * the latter is true if it has {@link GLAutoDrawable}s to render and is not paused.
+     * Indicates whether this animator {@link #isStarted() is started} and {@link #isPaused() is not paused}.
      *
      * @see #start()
      * @see #stop()
@@ -56,7 +56,9 @@ public interface GLAnimatorControl extends FPSCounter {
     boolean isAnimating();
 
     /**
-     * Indicates whether this animator is running and paused.
+     * Indicates whether this animator {@link #isStarted() is started}
+     * and either {@link #pause() manually paused} or paused
+     * automatically due to no {@link #add(GLAutoDrawable) added} {@link GLAutoDrawable}s.
      *
      * @see #start()
      * @see #stop()
@@ -75,30 +77,38 @@ public interface GLAnimatorControl extends FPSCounter {
 
     /**
      * Starts this animator, if not running.
-     * <P>
+     * <p>
      * In most situations this method blocks until
      * completion, except when called from the animation thread itself
      * or in some cases from an implementation-internal thread like the
      * AWT event queue thread.
-     * <P>
+     * </p>
+     * <p>
+     * Note that an animator w/o {@link #add(GLAutoDrawable) added drawables}
+     * will be paused automatically.
+     * </p>
+     * <p>
      * If started, all counters (time, frames, ..) are reset to zero.
+     * </p>
      *
      * @return true is started due to this call,
      *         otherwise false, ie started already or unable to start.
      *
      * @see #stop()
      * @see #isAnimating()
+     * @see #isPaused()
      * @see #getThread()
      */
     boolean start();
 
     /**
      * Stops this animator.
-     * <P>
+     * <p>
      * In most situations this method blocks until
      * completion, except when called from the animation thread itself
      * or in some cases from an implementation-internal thread like the
      * AWT event queue thread.
+     * </p>
      *
      * @return true is stopped due to this call,
      *         otherwise false, ie not started or unable to stop.
@@ -111,13 +121,14 @@ public interface GLAnimatorControl extends FPSCounter {
 
     /**
      * Pauses this animator.
-     * <P>
+     * <p>
      * In most situations this method blocks until
      * completion, except when called from the animation thread itself
      * or in some cases from an implementation-internal thread like the
      * AWT event queue thread.
+     * </p>
      *
-     * @return  false if if not started or already paused, otherwise true
+     * @return  false if not started, already paused or failed to pause, otherwise true
      *
      * @see #resume()
      * @see #isAnimating()
@@ -126,15 +137,17 @@ public interface GLAnimatorControl extends FPSCounter {
 
     /**
      * Resumes animation if paused.
-     * <P>
+     * <p>
      * In most situations this method blocks until
      * completion, except when called from the animation thread itself
      * or in some cases from an implementation-internal thread like the
      * AWT event queue thread.
-     * <P>
+     * </p>
+     * <p>
      * If resumed, all counters (time, frames, ..) are reset to zero.
+     * </p>
      *
-     * @return false if if not started or not paused, otherwise true
+     * @return false if not started, not paused or unable to resume, otherwise true
      *
      * @see #pause()
      * @see #isAnimating()
@@ -142,13 +155,30 @@ public interface GLAnimatorControl extends FPSCounter {
     boolean resume();
 
     /**
-     * Removes a drawable from the animator's list of rendering drawables.<br>
+     * Adds a drawable to this animator's list of rendering drawables.
+     * <p>
+     * This allows the animator thread to become {@link #isAnimating() animating},
+     * in case the first drawable is added and the animator {@link #isStarted() is started}.
+     * </p>
+     *
+     * @param drawable the drawable to be added
+     * @throws IllegalArgumentException if drawable was already added to this animator
+     */
+    void add(GLAutoDrawable drawable);
+
+    /**
+     * Removes a drawable from the animator's list of rendering drawables.
+     * <p>
      * This method should get called in case a drawable becomes invalid,
-     * and will not be recovered.<br>
-     * This allows the animator thread to become idle in case the last drawable
-     * has reached it's end of life.<br>
-     * 
-     * @param drawable the to be removed drawable
+     * and will not be recovered.
+     * </p>
+     * <p>
+     * This allows the animator thread to become {@link #isAnimating() not animating},
+     * in case the last drawable has been removed.
+     * </p>
+     *
+     * @param drawable the drawable to be removed
+     * @throws IllegalArgumentException if drawable was not added to this animator
      */
     void remove(GLAutoDrawable drawable);
 }