Clarify API Doc: GLRunnable and it's GLAutoDrawable::invoke(..)

2 files changed, 25 insertions, 16 deletions

diff --git a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
index f0101a90c..c676535c8 100644
--- a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
@@ -181,22 +181,26 @@ public interface GLAutoDrawable extends GLDrawable {
 
   /** 
    * <p>
-   * Enqueues a one-shot {@link javax.media.opengl.GLRunnable GLRunnable},
-   * which will be executed with the next {@link #display()} call.</p>
+   * Enqueues a one-shot {@link GLRunnable},
+   * which will be executed within the next {@link #display()} call
+   * after all registered {@link GLEventListener}s 
+   * {@link GLEventListener#display(GLAutoDrawable) display(GLAutoDrawable)} 
+   * methods has been called.
+   * </p>
    * <p>
-   * If no {@link javax.media.opengl.GLAnimatorControl GLAnimatorControl} is animating (default),<br>
+   * If no {@link GLAnimatorControl} is animating (default),<br>
    * or if the current thread is the animator thread,<br>
    * a {@link #display()} call is issued after enqueue the <code>GLRunnable</code>.<br>
    * No extra synchronization is performed in case <code>wait</code> is true, since it is executed in the current thread.</p>
    * <p>
-   * If an {@link javax.media.opengl.GLAnimatorControl GLAnimatorControl} is animating,<br>
+   * If an {@link GLAnimatorControl} is animating,<br>
    * no {@link #display()} call is issued, since the animator thread performs it.<br>
    * If <code>wait</code> is true, the implementation waits until the <code>GLRunnable</code> is executed.<br>
    * </p><br>
    *
-   * @see #setAnimator(javax.media.opengl.GLAnimatorControl)
+   * @see #setAnimator(GLAnimatorControl)
    * @see #display()
-   * @see javax.media.opengl.GLRunnable
+   * @see GLRunnable
    */   
   public void invoke(boolean wait, GLRunnable glRunnable);
 
diff --git a/src/jogl/classes/javax/media/opengl/GLRunnable.java b/src/jogl/classes/javax/media/opengl/GLRunnable.java
index 141d07c19..1ae1c9b22 100644
--- a/src/jogl/classes/javax/media/opengl/GLRunnable.java
+++ b/src/jogl/classes/javax/media/opengl/GLRunnable.java
@@ -30,23 +30,28 @@ package javax.media.opengl;
 
 /**
  * <p>
- * Declares one-shot OpenGL commands usable for injection into a {@link GLAutoDrawable},<br>
+ * Declares a one-shot OpenGL command usable for injection
  * via {@link GLAutoDrawable#invoke(boolean, javax.media.opengl.GLRunnable)}.<br>
- * {@link GLAutoDrawable} executes these commands within it's {@link GLAutoDrawable#display()}
- * method while the OpenGL context is current.<br>
+ * {@link GLAutoDrawable} executes the GLRunnables within it's {@link GLAutoDrawable#display() display()}
+ * method after all registered {@link GLEventListener}s 
+ * {@link GLEventListener#display(GLAutoDrawable) display(GLAutoDrawable)} 
+ * methods has been called.
+ * </p>
+ * <p>
+ * The OpenGL context is current while executing the GLRunnable.
+ * </p>
  * <p>
  * This might be useful to inject OpenGL commands from an I/O event listener.
+ * </p>
  */
 public interface GLRunnable { 
     /**
-     * Initiate one-shot OpenGL commands with a valid current context, 
-     * processed by {@link GLAutoDrawable#display()}, enqueued by 
-     * {@link GLAutoDrawable#invoke(boolean, GLRunnable)}. 
-     *  
      * @param drawable the associated drawable and current context for this call
-     * @return true if the GL [back] framebuffer remain intact by this runnable, otherwise false.
-     *         If returning false and hence the impl signals an invalidated back buffer,
-     *         another {@link GLEventListener#display(GLAutoDrawable)} call will be issued.
+     * @return true if the GL [back] framebuffer remains intact by this runnable, otherwise false.
+     *         If returning false {@link GLAutoDrawable} will call
+     *         {@link GLEventListener#display(GLAutoDrawable) display(GLAutoDrawable)} 
+     *         of all registered {@link GLEventListener}s once more. 
+     * @see GLRunnable
      */
     boolean run(GLAutoDrawable drawable);
 }