Fix some JavaDoc and API doc (reference) bugs ..

9 files changed, 65 insertions, 54 deletions

diff --git a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
index bdbbd96a5..989a61aaf 100644
--- a/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLAutoDrawable.java
@@ -48,12 +48,14 @@ import jogamp.opengl.Debug;
     an event based mechanism ({@link GLEventListener}) for performing
     OpenGL rendering. A GLAutoDrawable automatically creates a primary
     rendering context which is associated with the GLAutoDrawable for
-    the lifetime of the object. This context has the {@link
-    GLContext#setSynchronized synchronized} property enabled so that
-    calls to {@link GLContext#makeCurrent makeCurrent} will block if
-    the context is current on another thread. This allows the internal
-    GLContext for the GLAutoDrawable to be used both by the event
-    based rendering mechanism as well by end users directly.
+    the lifetime of the object.
+    <p>
+    Since the {@link GLContext} {@link GLContext#makeCurrent makeCurrent} 
+    implementation is synchronized, i.e. blocks if the context 
+    is current on another thread, the internal
+    {@link GLContext} for the GLAutoDrawable can be used for the event
+    based rendering mechanism and by end users directly.
+    </p>
     <p>
     The implementation shall initialize itself as soon as possible,
     ie if the attached {@link javax.media.nativewindow.NativeSurface NativeSurface} becomes visible/realized.
@@ -310,9 +312,9 @@ public interface GLAutoDrawable extends GLDrawable {
    * <p>
    * Impacts {@link #display()} and {@link #invoke(boolean, GLRunnable)} semantics.</p><br>
    *
-   * @param animator <code>null</code> reference indicates no animator is using
-   *                 this <code>GLAutoDrawable</code>,<br>
-   *                 a valid reference indicates an animator is using this <code>GLAutoDrawable</code>.
+   * @param animatorControl <code>null</code> reference indicates no animator is using
+   *                        this <code>GLAutoDrawable</code>,<br>
+   *                        a valid reference indicates an animator is using this <code>GLAutoDrawable</code>.
    *
    * @throws GLException if an animator is already registered.
    * @see #display()
@@ -406,7 +408,7 @@ public interface GLAutoDrawable extends GLDrawable {
    * @see #setAnimator(GLAnimatorControl)
    * @see #display()
    * @see GLRunnable
-   * @see #enqueue(GLRunnable)
+   * @see #invoke(boolean, List)
    */
   public boolean invoke(boolean wait, GLRunnable glRunnable);
   
@@ -416,6 +418,7 @@ public interface GLAutoDrawable extends GLDrawable {
    * @param wait if <code>true</code> block until execution of the last <code>glRunnable</code> is finished, otherwise return immediately w/o waiting
    * @param glRunnables the {@link GLRunnable}s to execute within {@link #display()}
    * @return <code>true</code> if the {@link GLRunnable}s has been processed or queued, otherwise <code>false</code>.
+   * @see #invoke(boolean, GLRunnable)
    */
   public boolean invoke(boolean wait, List<GLRunnable> glRunnables);
 
@@ -540,7 +543,6 @@ public interface GLAutoDrawable extends GLDrawable {
    * This method may also return <code>null</code> if no UI toolkit is being used,
    * as common for offscreen rendering.
    * </p>
-   * @return
    */
   public Object getUpstreamWidget();
 
diff --git a/src/jogl/classes/javax/media/opengl/GLBase.java b/src/jogl/classes/javax/media/opengl/GLBase.java
index 07dfc7e72..1f75a7b4a 100644
--- a/src/jogl/classes/javax/media/opengl/GLBase.java
+++ b/src/jogl/classes/javax/media/opengl/GLBase.java
@@ -436,7 +436,6 @@ public interface GLBase {
     * NPOT textures are supported in OpenGL >= 3, GLES2 or if the
     * 'GL_ARB_texture_non_power_of_two' extension is available.
     * </p>
-    * @return
     */
    public boolean isNPOTTextureAvailable();
 
@@ -518,12 +517,12 @@ public interface GLBase {
    public long glGetBufferSize(int buffer);
 
    /**
-    * @return true if a VBO is bound to {@link GL.GL_ARRAY_BUFFER} via {@link GL#glBindBuffer(int, int)}, otherwise false
+    * @return true if a VBO is bound to {@link GL#GL_ARRAY_BUFFER} via {@link GL#glBindBuffer(int, int)}, otherwise false
     */
    public boolean glIsVBOArrayBound();
 
    /**
-    * @return true if a VBO is bound to {@link GL.GL_ELEMENT_ARRAY_BUFFER} via {@link GL#glBindBuffer(int, int)}, otherwise false
+    * @return true if a VBO is bound to {@link GL#GL_ELEMENT_ARRAY_BUFFER} via {@link GL#glBindBuffer(int, int)}, otherwise false
     */
    public boolean glIsVBOElementArrayBound();
 
@@ -537,7 +536,7 @@ public interface GLBase {
     * Return the default draw framebuffer name.
     * <p> 
     * May differ from it's default <code>zero</code>
-    * in case an framebuffer object ({@link FBObject}) based drawable
+    * in case an framebuffer object ({@link com.jogamp.opengl.FBObject}) based drawable
     * is being used.
     * </p> 
     */
@@ -547,7 +546,7 @@ public interface GLBase {
     * Return the default read framebuffer name.
     * <p> 
     * May differ from it's default <code>zero</code>
-    * in case an framebuffer object ({@link FBObject}) based drawable
+    * in case an framebuffer object ({@link com.jogamp.opengl.FBObject}) based drawable
     * is being used.
     * </p> 
     */
diff --git a/src/jogl/classes/javax/media/opengl/GLCapabilities.java b/src/jogl/classes/javax/media/opengl/GLCapabilities.java
index 5b3eb9119..872069fb8 100644
--- a/src/jogl/classes/javax/media/opengl/GLCapabilities.java
+++ b/src/jogl/classes/javax/media/opengl/GLCapabilities.java
@@ -50,7 +50,8 @@ import javax.media.nativewindow.CapabilitiesImmutable;
     must support, such as the OpenGL profile, color depth and whether stereo is enabled.<br>
 
     The actual capabilites of created {@link GLDrawable}s are then reflected by their own
-    GLCapabilites instance, which can be queried with {@link GLDrawable#getGLCapabilities()}.<br>
+    GLCapabilites instance, which can be queried with {@link GLDrawable#getChosenGLCapabilities()}.
+    <br>
 
     It currently contains the minimal number of routines which allow
     configuration on all supported window systems. */
@@ -246,7 +247,7 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil
   /**
    * Requesting offscreen pbuffer mode.
    * <p>
-   * If enabled this method also invokes {@link #setOnscreen(int) setOnscreen(false)}.
+   * If enabled this method also invokes {@link #setOnscreen(boolean) setOnscreen(false)}.
    * </p>
    * <p>
    * Defaults to false.
@@ -270,7 +271,7 @@ public class GLCapabilities extends Capabilities implements Cloneable, GLCapabil
   /**
    * Requesting offscreen FBO mode.
    * <p>
-   * If enabled this method also invokes {@link #setOnscreen(int) setOnscreen(false)}.
+   * If enabled this method also invokes {@link #setOnscreen(boolean) setOnscreen(false)}.
    * </p>
    * <p>
    * Defaults to false.
diff --git a/src/jogl/classes/javax/media/opengl/GLContext.java b/src/jogl/classes/javax/media/opengl/GLContext.java
index 618ee2584..854d96807 100644
--- a/src/jogl/classes/javax/media/opengl/GLContext.java
+++ b/src/jogl/classes/javax/media/opengl/GLContext.java
@@ -283,8 +283,9 @@ public abstract class GLContext {
    *                     this context is made current on another thread.
    *
    * @see #isGLReadDrawableAvailable()
+   * @see #setGLReadDrawable(GLDrawable)
    * @see #getGLReadDrawable()
-   * @see #setGLReadDrawable()
+   * @see #setGLDrawable(GLDrawable, boolean)
    * @see #getGLDrawable()
    */
   public abstract GLDrawable setGLDrawable(GLDrawable readWrite, boolean setWriteOnly);
@@ -334,8 +335,8 @@ public abstract class GLContext {
    * it equals to the write-drawable (default).
    * </p> 
    * @see #isGLReadDrawableAvailable()
-   * @see #setGLReadDrawable(javax.media.opengl.GLDrawable)
-   * @see #getGLDrawable()
+   * @see #setGLReadDrawable(GLDrawable)
+   * @see #getGLReadDrawable() 
    */
   public abstract GLDrawable getGLReadDrawable();
 
@@ -407,7 +408,7 @@ public abstract class GLContext {
    * parameter indicates which groups of state variables are to be
    * copied. <code>mask</code> contains the bitwise OR of the same
    * symbolic names that are passed to the GL command {@link
-   * GL#glPushAttrib glPushAttrib}. The single symbolic constant
+   * GL2#glPushAttrib glPushAttrib}. The single symbolic constant
    * {@link GL2#GL_ALL_ATTRIB_BITS GL_ALL_ATTRIB_BITS} can be used to
    * copy the maximum possible portion of rendering state. <P>
    *
@@ -1115,7 +1116,9 @@ public abstract class GLContext {
 
   /** 
    * Indicates whether this GLContext is capable of GL2ES3. <p>Includes [ GL4bc, GL4, GL3bc, GL3, GLES3, GL3ES3, GL2, GL2GL3 ].</p>
-   * @see GLProfile#isGL2ES3() 
+   * @see GLProfile#isGL2ES3()
+   * @see #isGL3ES3()
+   * @see #isGL2GL3()
    */
   public final boolean isGL2ES3() {
       return isGL3ES3() || isGL2GL3();
@@ -1216,7 +1219,7 @@ public abstract class GLContext {
    * Return the default draw framebuffer name.
    * <p> 
    * May differ from it's default <code>zero</code>
-   * in case an framebuffer object ({@link FBObject}) based drawable
+   * in case an framebuffer object ({@link com.jogamp.opengl.FBObject}) based drawable
    * is being used.
    * </p> 
    */
@@ -1226,7 +1229,7 @@ public abstract class GLContext {
    * Return the default read framebuffer name.
    * <p> 
    * May differ from it's default <code>zero</code>
-   * in case an framebuffer object ({@link FBObject}) based drawable
+   * in case an framebuffer object ({@link com.jogamp.opengl.FBObject}) based drawable
    * is being used.
    * </p> 
    */
@@ -1253,23 +1256,23 @@ public abstract class GLContext {
   
   /**
    * @return The extension implementing the GLDebugOutput feature,
-   *         either <i>GL_ARB_debug_output</i> or <i>GL_AMD_debug_output</i>.
+   *         either {@link GLExtensions#ARB_debug_output} or {@link GLExtensions#AMD_debug_output}.
    *         If unavailable or called before initialized via {@link #makeCurrent()}, <i>null</i> is returned.
    */
   public abstract String getGLDebugMessageExtension();
 
   /**
-   * @return the current synchronous debug behavior via
-   * @see #setSynchronous(boolean)
+   * @return the current synchronous debug behavior, set via {@link #setGLDebugSynchronous(boolean)}.
    */
   public abstract boolean isGLDebugSynchronous();
 
   /**
    * Enables or disables the synchronous debug behavior via
-   * {@link GL2GL3#GL_DEBUG_OUTPUT_SYNCHRONOUS_ARB glEnable/glDisable(GL_DEBUG_OUTPUT_SYNCHRONOUS_ARB)},
-   * if extension is {@link #GL_ARB_debug_output}.
-   * There is no equivalent for {@link #GL_AMD_debug_output}.
-   * <p> The default is <code>true</code>, ie {@link GL2GL3#GL_DEBUG_OUTPUT_SYNCHRONOUS_ARB}.</p>
+   * {@link GL2GL3#GL_DEBUG_OUTPUT_SYNCHRONOUS glEnable/glDisable(GL_DEBUG_OUTPUT_SYNCHRONOUS)},
+   * if extension is {@link GLExtensions#ARB_debug_output}.
+   * There is no equivalent for {@link GLExtensions#AMD_debug_output}.
+   * <p> The default is <code>true</code>, ie {@link GL2GL3#GL_DEBUG_OUTPUT_SYNCHRONOUS}.</p>
+   * @link {@link #isGLDebugSynchronous()}
    */
   public abstract void setGLDebugSynchronous(boolean synchronous);
 
@@ -1279,8 +1282,8 @@ public abstract class GLContext {
   public abstract boolean isGLDebugMessageEnabled();
 
   /**
-   * Enables or disables the GLDebugOutput feature of extension <i>GL_ARB_debug_output</i>
-   * or <i>GL_AMD_debug_output</i>, if available.
+   * Enables or disables the GLDebugOutput feature of extension {@link GLExtensions#ARB_debug_output}
+   * or {@link GLExtensions#AMD_debug_output}, if available.
    *
    * <p>To enable the GLDebugOutput feature {@link #enableGLDebugMessage(boolean) enableGLDebugMessage(true)}
    * or {@link #setContextCreationFlags(int) setContextCreationFlags}({@link GLContext#CTX_OPTION_DEBUG})
@@ -1305,7 +1308,7 @@ public abstract class GLContext {
   /**
    * Add {@link GLDebugListener}.<br>
    *
-   * @param listener {@link GLDebugListener} handling {@GLDebugMessage}s
+   * @param listener {@link GLDebugListener} handling {@link GLDebugMessage}s
    * @see #enableGLDebugMessage(boolean)
    * @see #removeGLDebugListener(GLDebugListener)
    */
@@ -1314,28 +1317,28 @@ public abstract class GLContext {
   /**
    * Remove {@link GLDebugListener}.<br>
    *
-   * @param listener {@link GLDebugListener} handling {@GLDebugMessage}s
+   * @param listener {@link GLDebugListener} handling {@link GLDebugMessage}s
    * @see #enableGLDebugMessage(boolean)
    * @see #addGLDebugListener(GLDebugListener)
    */
   public abstract void removeGLDebugListener(GLDebugListener listener);
 
   /**
-   * Generic entry for {@link GL2GL3#glDebugMessageControlARB(int, int, int, int, IntBuffer, boolean)}
+   * Generic entry for {@link GL2GL3#glDebugMessageControl(int, int, int, int, IntBuffer, boolean)}
    * and {@link GL2GL3#glDebugMessageEnableAMD(int, int, int, IntBuffer, boolean)} of the GLDebugOutput feature.
    * @see #enableGLDebugMessage(boolean)
    */
   public abstract void glDebugMessageControl(int source, int type, int severity, int count, IntBuffer ids, boolean enabled);
 
   /**
-   * Generic entry for {@link GL2GL3#glDebugMessageControlARB(int, int, int, int, int[], int, boolean)}
+   * Generic entry for {@link GL2GL3#glDebugMessageControl(int, int, int, int, int[], int, boolean)}
    * and {@link GL2GL3#glDebugMessageEnableAMD(int, int, int, int[], int, boolean)} of the GLDebugOutput feature.
    * @see #enableGLDebugMessage(boolean)
    */
   public abstract void glDebugMessageControl(int source, int type, int severity, int count, int[] ids, int ids_offset, boolean enabled);
 
   /**
-   * Generic entry for {@link GL2GL3#glDebugMessageInsertARB(int, int, int, int, int, String)}
+   * Generic entry for {@link GL2GL3#glDebugMessageInsert(int, int, int, int, int, String)}
    * and {@link GL2GL3#glDebugMessageInsertAMD(int, int, int, int, String)} of the GLDebugOutput feature.
    * @see #enableGLDebugMessage(boolean)
    */
@@ -1485,8 +1488,8 @@ public abstract class GLContext {
   }
 
   /**
-   * Called by {@link jogamp.opengl.GLContextImpl#createContextARBMapVersionsAvailable} not intended to be used by
-   * implementations. However, if {@link #createContextARB} is not being used within
+   * Called by {@link jogamp.opengl.GLContextImpl#createContextARBMapVersionsAvailable(int,int)} not intended to be used by
+   * implementations. However, if {@link jogamp.opengl.GLContextImpl#createContextARB(long, boolean)} is not being used within
    * {@link javax.media.opengl.GLDrawableFactory#getOrCreateSharedContext(javax.media.nativewindow.AbstractGraphicsDevice)},
    * GLProfile has to map the available versions.
    *
diff --git a/src/jogl/classes/javax/media/opengl/GLDebugMessage.java b/src/jogl/classes/javax/media/opengl/GLDebugMessage.java
index f8959e653..4b8d62898 100644
--- a/src/jogl/classes/javax/media/opengl/GLDebugMessage.java
+++ b/src/jogl/classes/javax/media/opengl/GLDebugMessage.java
@@ -29,6 +29,10 @@ package javax.media.opengl;
 
 import com.jogamp.common.os.Platform;
 
+/**
+ * OpenGL debug message generated by the driver 
+ * and delivered via {@link GLDebugListener}.
+ */
 public class GLDebugMessage {
     final GLContext source;
     final long when;    
diff --git a/src/jogl/classes/javax/media/opengl/GLDrawable.java b/src/jogl/classes/javax/media/opengl/GLDrawable.java
index 369ea6d2b..46fa923ad 100644
--- a/src/jogl/classes/javax/media/opengl/GLDrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLDrawable.java
@@ -202,7 +202,7 @@ public interface GLDrawable {
    * <p>
    * On EGL it is represented by the EGLSurface.<br>
    * On X11/GLX it is represented by either the Window XID, GLXPixmap, or GLXPbuffer.<br>
-   * On Windows it is represented by the HDC, which may change with each {@link #lockSurface()}.<br>
+   * On Windows it is represented by the HDC, which may change with each {@link NativeSurface#lockSurface()}.<br>
    * </p>
    * @see #setRealized(boolean)
    * @see NativeSurface#lockSurface()
diff --git a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
index c2e7e0829..7c3c42e45 100644
--- a/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
+++ b/src/jogl/classes/javax/media/opengl/GLDrawableFactory.java
@@ -336,7 +336,7 @@ public abstract class GLDrawableFactory {
    * @param device which {@link javax.media.nativewindow.AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be <code>null</code> for the platform's default device.
    * @param quirk the quirk to be tested, e.g. {@link GLRendererQuirks#NoDoubleBufferedPBuffer}.
    * @throws IllegalArgumentException if the quirk is out of range
-   * @see #getRendererQuirks()
+   * @see #getRendererQuirks(AbstractGraphicsDevice)
    * @see GLRendererQuirks
    */
   public final boolean hasRendererQuirk(AbstractGraphicsDevice device, int quirk) {
@@ -459,7 +459,7 @@ public abstract class GLDrawableFactory {
    * @see javax.media.opengl.GLCapabilities#isOnscreen()
    * @see javax.media.opengl.GLCapabilities#isFBO()
    * @see javax.media.opengl.GLCapabilities#isPBuffer()
-   * @see javax.media.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen)
+   * @see javax.media.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration(CapabilitiesImmutable, CapabilitiesImmutable, javax.media.nativewindow.CapabilitiesChooser, AbstractGraphicsScreen, int)
    */
   public abstract GLDrawable createGLDrawable(NativeSurface target)
     throws IllegalArgumentException, GLException;
@@ -560,7 +560,8 @@ public abstract class GLDrawableFactory {
   public abstract GLDrawable createDummyDrawable(AbstractGraphicsDevice deviceReq, boolean createNewDevice, GLProfile glp);
   
   /**
-   * Creates a proxy {@link NativeSurface} w/ defined surface handle, i.e. a {@link WrappedSurface} or {@link GDISurface} instance. 
+   * Creates a proxy {@link NativeSurface} w/ defined surface handle, 
+   * i.e. a {@link jogamp.nativewindow.WrappedSurface} or {@link jogamp.nativewindow.windows.GDISurface} instance. 
    * <p>
    * It's {@link AbstractGraphicsConfiguration} is properly set according to the given 
    * <code>windowHandle</code>'s native visualID if set or the given {@link GLCapabilitiesImmutable}.
@@ -571,7 +572,8 @@ public abstract class GLDrawableFactory {
    * </p>
    * <p>
    * Such surface can be used to instantiate a GLDrawable. With the help of {@link GLAutoDrawableDelegate}
-   * you will be able to implement a new native windowing system  binding almost on-the-fly, see {@link com.jogamp.opengl.swt.GLCanvas}. 
+   * you will be able to implement a new native windowing system  binding almost on-the-fly, 
+   * see {@link com.jogamp.opengl.swt.GLCanvas}. 
    * </p>
    * 
    * @param device which {@link javax.media.nativewindow.AbstractGraphicsDevice#getConnection() connection} denotes the shared the target device, may be <code>null</code> for the platform's default device.
@@ -580,7 +582,7 @@ public abstract class GLDrawableFactory {
    * @param windowHandle the native window handle
    * @param caps the requested GLCapabilties
    * @param chooser the custom chooser, may be null for default
-   * @param upstream optional {@link ProxySurface.UpstreamSurfaceHook} allowing control of the {@link ProxySurface}'s lifecycle and data it presents.
+   * @param upstream optional {@link UpstreamSurfaceHook} allowing control of the {@link ProxySurface}'s lifecycle and data it presents.
    * @return the created {@link ProxySurface} instance w/ defined surface handle.
    */
   public abstract ProxySurface createProxySurface(AbstractGraphicsDevice device,
diff --git a/src/jogl/classes/javax/media/opengl/GLFBODrawable.java b/src/jogl/classes/javax/media/opengl/GLFBODrawable.java
index 4d6c7c20e..df38745d5 100644
--- a/src/jogl/classes/javax/media/opengl/GLFBODrawable.java
+++ b/src/jogl/classes/javax/media/opengl/GLFBODrawable.java
@@ -62,14 +62,14 @@ import com.jogamp.opengl.FBObject.TextureAttachment;
  * </p>
  * <p>
  * It would be possible to implement double buffering simply using 
- * {@link FBObject.TextureAttachment texture attachment}s with one {@link FBObject framebuffer}.
+ * {@link TextureAttachment}s with one {@link FBObject framebuffer}.
  * This would require mode selection and hence complicate the API. Besides, it would
  * not support differentiation of read and write framebuffer and hence not be spec compliant.
  * </p>
  * <p>
- * Actual swapping of the {@link FBObject.TextureAttachment texture}s or {@link FBObject framebuffer}
- * is performed either in the {@link #contextMadeCurrent(boolean) context current hook}
- * or when {@link #swapBuffersImpl(boolean) swapping buffers}, whatever comes first.<br/>
+ * Actual swapping of the {@link TextureAttachment texture}s and/or {@link FBObject framebuffer}
+ * is performed either in the {@link jogamp.opengl.GLContextImpl#contextMadeCurrent(boolean) context current hook}
+ * or when {@link jogamp.opengl.GLDrawableImpl#swapBuffersImpl(boolean) swapping buffers}, whatever comes first.
  * </p>
  */ 
 public interface GLFBODrawable extends GLDrawable {
diff --git a/src/jogl/classes/javax/media/opengl/GLProfile.java b/src/jogl/classes/javax/media/opengl/GLProfile.java
index b5e89a23b..1dde2cbb6 100644
--- a/src/jogl/classes/javax/media/opengl/GLProfile.java
+++ b/src/jogl/classes/javax/media/opengl/GLProfile.java
@@ -1130,8 +1130,8 @@ public class GLProfile {
 
     /** 
      * Indicates whether this profile is capable of GL2ES3. <p>Includes [ GL4bc, GL4, GL3bc, GL3, GLES3, GL3ES3, GL2, GL2GL3 ].</p>
-     * @see isGL3ES3() 
-     * @see isGL2GL3() 
+     * @see #isGL3ES3() 
+     * @see #isGL2GL3() 
      */
     public final boolean isGL2ES3() {
         return isGL3ES3() || isGL2GL3();