Refine API doc

2 files changed, 12 insertions, 10 deletions

diff --git a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
index c427a9804..f0101a90c 100644
--- a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
@@ -181,15 +181,15 @@ public interface GLAutoDrawable extends GLDrawable {
 
   /** 
    * <p>
-   * Enqueues a one-shot {@link javax.media.opengl.GLRunnable},
+   * Enqueues a one-shot {@link javax.media.opengl.GLRunnable GLRunnable},
    * which will be executed with the next {@link #display()} call.</p>
    * <p>
-   * If no {@link javax.media.opengl.GLAnimatorControl} is registered, or if it is not animating, the default situation,<br>
+   * If no {@link javax.media.opengl.GLAnimatorControl 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 {@link javax.media.opengl.GLAnimatorControl} is registered and is animating,<br>
+   * If an {@link javax.media.opengl.GLAnimatorControl 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>
@@ -217,7 +217,7 @@ public interface GLAutoDrawable extends GLDrawable {
    * <ul>
    *     <li> Calling {@link GLEventListener#display display(..)} for all
    *          registered {@link GLEventListener}s. </li>
-   *     <li> Executes all one-shot {@link javax.media.opengl.GLRunnable},
+   *     <li> Executes all one-shot {@link javax.media.opengl.GLRunnable GLRunnable},
    *          enqueued via {@link #invoke(boolean, GLRunnable)}.</li>
    * </ul></p>
    * <p> 
diff --git a/src/jogl/classes/javax/media/opengl/GLRunnable.java b/src/jogl/classes/javax/media/opengl/GLRunnable.java
index cbd086c77..141d07c19 100644
--- a/src/jogl/classes/javax/media/opengl/GLRunnable.java
+++ b/src/jogl/classes/javax/media/opengl/GLRunnable.java
@@ -39,12 +39,14 @@ package javax.media.opengl;
  */
 public interface GLRunnable { 
     /**
-     * Called by the drawable to initiate one-shot OpenGL commands by the
-     * client, like {@link GLEventListener#display(GLAutoDrawable)}.
-     * 
-     * @param drawable the associated drawable the implementation shall use
-     * @return false if impl invalidates the back buffers, hence {@link GLAutoDrawable#display()} will 
-     *         issue another {@link GLEventListener#display(GLAutoDrawable)} call. Otherwise true.
+     * 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.
      */
     boolean run(GLAutoDrawable drawable);
 }