#1107 - Javadoc warning cleanup & Fix for JDK 11 Javadoc NPE (#1118)

* Fixed "broken" @see tags causing Javadoc NPE in JDK 11

* Updated comments to clear Javadoc warnings in JDK 11

* Added @Deprecated annotations to clear JDK 11 Javadoc warnings

jme3-core/src/main/java/com/jme3/audio/AudioNode.java

@@ -158,6 +158,7 @@ public class AudioNode extends Node implements AudioSource {
      *
      * @deprecated Use {@link AudioNode#AudioNode(com.jme3.asset.AssetManager, java.lang.String, com.jme3.audio.AudioData.DataType)} instead
      */
+    @Deprecated
     public AudioNode(AssetManager assetManager, String name, boolean stream, boolean streamCache) {
         this.audioKey = new AudioKey(name, stream, streamCache);
         this.data = (AudioData) assetManager.loadAsset(audioKey);
@@ -173,6 +174,7 @@ public class AudioNode extends Node implements AudioSource {
      *
      * @deprecated Use {@link AudioNode#AudioNode(com.jme3.asset.AssetManager, java.lang.String, com.jme3.audio.AudioData.DataType)} instead
      */
+    @Deprecated
     public AudioNode(AssetManager assetManager, String name, boolean stream) {
         this(assetManager, name, stream, true); // Always streamCached
     }
@@ -186,6 +188,7 @@ public class AudioNode extends Node implements AudioSource {
      *
      * @deprecated AudioRenderer parameter is ignored.
      */
+    @Deprecated
     public AudioNode(AudioRenderer audioRenderer, AssetManager assetManager, String name) {
         this(assetManager, name, DataType.Buffer);
     }
@@ -197,6 +200,7 @@ public class AudioNode extends Node implements AudioSource {
      * @param name The filename of the audio file
      * @deprecated Use {@link AudioNode#AudioNode(com.jme3.asset.AssetManager, java.lang.String, com.jme3.audio.AudioData.DataType) } instead
      */
+    @Deprecated
     public AudioNode(AssetManager assetManager, String name) {
         this(assetManager, name, DataType.Buffer);
     }

jme3-core/src/main/java/com/jme3/input/AbstractJoystick.java

@@ -98,6 +98,7 @@ public abstract class AbstractJoystick implements Joystick {
      * @deprecated Use JoystickButton.assignButton() instead.
      */
     @Override
+    @Deprecated
     public void assignButton(String mappingName, int buttonId){
         if (buttonId < 0 || buttonId >= getButtonCount())
             throw new IllegalArgumentException();
@@ -116,6 +117,7 @@ public abstract class AbstractJoystick implements Joystick {
      * @deprecated Use JoystickAxis.assignAxis() instead.
      */
     @Override
+    @Deprecated
     public void assignAxis(String positiveMapping, String negativeMapping, int axisId){
     
         // For backwards compatibility

jme3-core/src/main/java/com/jme3/input/InputManager.java

@@ -776,6 +776,7 @@ public class InputManager implements RawInputListener {
      * Returns state of simulation of mouse events. Used for touchscreen input only.
      *
      */
+    @Deprecated
     public boolean getSimulateMouse() {
         if (touch != null) {
             return touch.isSimulateMouse();

jme3-core/src/main/java/com/jme3/input/Joystick.java

@@ -57,6 +57,7 @@ public interface Joystick {
      * @see Joystick#getButtonCount()
      * @deprecated Use JoystickButton.assignButton() instead.
      */
+    @Deprecated
     public void assignButton(String mappingName, int buttonId);
 
     /**
@@ -69,6 +70,7 @@ public interface Joystick {
      * @see Joystick#getAxisCount()
      * @deprecated Use JoystickAxis.assignAxis() instead.
      */
+    @Deprecated
     public void assignAxis(String positiveMapping, String negativeMapping, int axisId); 
 
     /**

jme3-core/src/main/java/com/jme3/material/RenderState.java

@@ -1242,6 +1242,7 @@ public class RenderState implements Cloneable, Savable {
      * material parameter.
      * @return false
      */
+    @Deprecated
     public boolean isAlphaTest() {
         return false;
     }

jme3-core/src/main/java/com/jme3/texture/Texture.java

@@ -248,6 +248,7 @@ public abstract class Texture implements CloneableSmartAsset, Savable, Cloneable
          * 
          * @deprecated Not supported by OpenGL 3
          */
+        @Deprecated
         MirrorEdgeClamp;
     }
 

jme3-vr/src/main/java/com/jme3/input/vr/VRInputAPI.java

@@ -123,7 +123,7 @@ public interface VRInputAPI {
     public Object getRawControllerState(int index);
     
     /**
-     * Swap the two hands (exchange the hands controller 1 & 2 indices).
+     * Swap the two hands (exchange the hands controller 1 and 2 indices).
      */
     public void swapHands();
     

jme3-vr/src/main/java/com/jme3/input/vr/oculus/OculusVR.java

@@ -33,7 +33,7 @@ import static org.lwjgl.system.MemoryUtil.*;
  * <li>Vectors should have their X and Z axes flipped, but apparently not Y.</li>
  * </ul>
  *
- * @author Campbell Suter <[email protected]>
+ * @author Campbell Suter ([email protected])
  */
 public class OculusVR implements VRAPI {
 

jme3-vr/src/main/java/com/jme3/input/vr/oculus/OculusViewManager.java

@@ -55,7 +55,7 @@ import static org.lwjgl.ovr.OVRErrorCode.*;
 /**
  * A rendering system for Oculus's LibOVR API.
  *
- * @author Campbell Suter <[email protected]>
+ * @author Campbell Suter ([email protected])
  */
 public class OculusViewManager extends AbstractVRViewManager {
 

jme3-vr/src/main/java/com/jme3/post/CartoonSSAO.java

@@ -43,7 +43,7 @@ public class CartoonSSAO extends Filter{
 
     /**
     * Create a Screen Space Ambient Occlusion Filter.
-    * @param downsample factor to divide resolution by for filter, >1 increases speed but degrades quality.
+    * @param downsample factor to divide resolution by for filter, >1 increases speed but degrades quality.
     * @param instancedRendering <code>true</code> if this filter has to use instance rendering and <code>false</code> (default) otherwise.
     */
     public CartoonSSAO(float downsample, boolean instancedRendering) {

jme3-vr/src/main/java/com/jme3/system/jopenvr/CameraVideoStreamFrameHeader_t.java

@@ -27,7 +27,7 @@ public class CameraVideoStreamFrameHeader_t extends Structure {
 		return Arrays.asList("eFrameType", "nWidth", "nHeight", "nBytesPerPixel", "nFrameSequence", "standingTrackedDevicePose");
 	}
 	/**
-	 * @param eFrameType @see EVRTrackedCameraFrameType<br>
+	 * @param eFrameType @see JOpenVRLibrary.EVRTrackedCameraFrameType <br>
 	 * C type : EVRTrackedCameraFrameType<br>
 	 * @param standingTrackedDevicePose C type : TrackedDevicePose_t
 	 */

jme3-vr/src/main/java/com/jme3/system/jopenvr/Texture_t.java

@@ -32,9 +32,9 @@ public class Texture_t extends Structure {
 	/**
 	 * @param handle void *<br>
 	 * C type : void*<br>
-	 * @param eType @see ETextureType<br>
+	 * @param eType @see JOpenVRLibrary.ETextureType <br>
 	 * C type : ETextureType<br>
-	 * @param eColorSpace @see EColorSpace<br>
+	 * @param eColorSpace @see JOpenVRLibrary.EColorSpace <br>
 	 * C type : EColorSpace
 	 */
 	public Texture_t(int handle, int eType, int eColorSpace) {

jme3-vr/src/main/java/com/jme3/system/jopenvr/TrackedDevicePose_t.java

@@ -32,7 +32,7 @@ public class TrackedDevicePose_t extends Structure {
 	 * @param mDeviceToAbsoluteTracking C type : HmdMatrix34_t<br>
 	 * @param vVelocity C type : HmdVector3_t<br>
 	 * @param vAngularVelocity C type : HmdVector3_t<br>
-	 * @param eTrackingResult @see ETrackingResult<br>
+	 * @param eTrackingResult @see JOpenVRLibrary.ETrackingResult <br>
 	 * C type : ETrackingResult
 	 */
 	public TrackedDevicePose_t(HmdMatrix34_t mDeviceToAbsoluteTracking, HmdVector3_t vVelocity, HmdVector3_t vAngularVelocity, int eTrackingResult, byte bPoseIsValid, byte bDeviceIsConnected) {

jme3-vr/src/main/java/com/jme3/system/jopenvr/VREvent_DualAnalog_t.java

@@ -25,7 +25,7 @@ public class VREvent_DualAnalog_t extends Structure {
 		return Arrays.asList("x", "y", "transformedX", "transformedY", "which");
 	}
 	/**
-	 * @param which @see EDualAnalogWhich<br>
+	 * @param which @see JOpenVRLibrary.EDualAnalogWhich <br>
 	 * C type : EDualAnalogWhich
 	 */
 	public VREvent_DualAnalog_t(float x, float y, float transformedX, float transformedY, int which) {

jme3-vr/src/main/java/com/jme3/system/jopenvr/VREvent_Property_t.java

@@ -24,7 +24,7 @@ public class VREvent_Property_t extends Structure {
 	}
 	/**
 	 * @param container C type : PropertyContainerHandle_t<br>
-	 * @param prop @see ETrackedDeviceProperty<br>
+	 * @param prop @see JOpenVRLibrary.ETrackedDeviceProperty <br>
 	 * C type : ETrackedDeviceProperty
 	 */
 	public VREvent_Property_t(long container, int prop) {

jme3-vr/src/main/java/com/jme3/system/jopenvr/VROverlayIntersectionMaskPrimitive_t.java

@@ -23,7 +23,7 @@ public class VROverlayIntersectionMaskPrimitive_t extends Structure {
 		return Arrays.asList("m_nPrimitiveType", "m_Primitive");
 	}
 	/**
-	 * @param m_nPrimitiveType @see EVROverlayIntersectionMaskPrimitiveType<br>
+	 * @param m_nPrimitiveType @see JOpenVRLibrary.EVROverlayIntersectionMaskPrimitiveType <br>
 	 * C type : EVROverlayIntersectionMaskPrimitiveType<br>
 	 * @param m_Primitive C type : VROverlayIntersectionMaskPrimitive_Data_t
 	 */

jme3-vr/src/main/java/com/jme3/system/jopenvr/VROverlayIntersectionParams_t.java

@@ -27,7 +27,7 @@ public class VROverlayIntersectionParams_t extends Structure {
 	/**
 	 * @param vSource C type : HmdVector3_t<br>
 	 * @param vDirection C type : HmdVector3_t<br>
-	 * @param eOrigin @see ETrackingUniverseOrigin<br>
+	 * @param eOrigin @see JOpenVRLibrary.ETrackingUniverseOrigin <br>
 	 * C type : ETrackingUniverseOrigin
 	 */
 	public VROverlayIntersectionParams_t(HmdVector3_t vSource, HmdVector3_t vDirection, int eOrigin) {

jme3-vr/src/main/java/com/jme3/system/osvr/osvrrendermanager/OSVR_ProjectionMatrix.java

@@ -13,7 +13,7 @@ public class OSVR_ProjectionMatrix extends Structure {
 	public double right;
 	public double top;
 	public double bottom;
-	/** < Cannot name "near" because Visual Studio keyword */
+	/** Cannot name "near" because Visual Studio keyword */
 	public double nearClip;
 	public double farClip;
 	public OSVR_ProjectionMatrix() {
@@ -22,7 +22,7 @@ public class OSVR_ProjectionMatrix extends Structure {
 	protected List<String> getFieldOrder() {
 		return Arrays.asList("left", "right", "top", "bottom", "nearClip", "farClip");
 	}
-	/** @param nearClip < Cannot name "near" because Visual Studio keyword */
+	/** @param nearClip Cannot name "near" because Visual Studio keyword */
 	public OSVR_ProjectionMatrix(double left, double right, double top, double bottom, double nearClip, double farClip) {
 		super();
 		this.left = left;

jme3-vr/src/main/java/com/jme3/system/osvr/osvrrendermanager/OSVR_RenderParams.java

@@ -10,12 +10,12 @@ import java.util.List;
  */
 public class OSVR_RenderParams extends Structure {
 	/**
-	 * < Room space to insert<br>
+	 * Room space to insert<br>
 	 * C type : OSVR_PoseState*
 	 */
 	public Pointer worldFromRoomAppend;
 	/**
-	 * < Overrides head space<br>
+	 * Overrides head space<br>
 	 * C type : OSVR_PoseState*
 	 */
 	public Pointer roomFromHeadReplace;
@@ -28,9 +28,9 @@ public class OSVR_RenderParams extends Structure {
 		return Arrays.asList("worldFromRoomAppend", "roomFromHeadReplace", "nearClipDistanceMeters", "farClipDistanceMeters");
 	}
 	/**
-	 * @param worldFromRoomAppend < Room space to insert<br>
+	 * @param worldFromRoomAppend Room space to insert<br>
 	 * C type : OSVR_PoseState*<br>
-	 * @param roomFromHeadReplace < Overrides head space<br>
+	 * @param roomFromHeadReplace Overrides head space<br>
 	 * C type : OSVR_PoseState*
 	 */
 	public OSVR_RenderParams(Pointer worldFromRoomAppend, Pointer roomFromHeadReplace, double nearClipDistanceMeters, double farClipDistanceMeters) {

jme3-vr/src/main/java/com/jme3/system/osvr/osvrrendermanager/OSVR_ViewportDescription.java

@@ -9,13 +9,13 @@ import java.util.List;
  * For help, please visit <a href="http://nativelibs4java.googlecode.com/">NativeLibs4Java</a> , <a href="http://rococoa.dev.java.net/">Rococoa</a>, or <a href="http://jna.dev.java.net/">JNA</a>.
  */
 public class OSVR_ViewportDescription extends Structure {
-	/** < Left side of the viewport in pixels */
+	/** Left side of the viewport in pixels */
 	public double left;
-	/** < First pixel in the viewport at the bottom. */
+	/** First pixel in the viewport at the bottom. */
 	public double lower;
-	/** < Last pixel in the viewport at the top */
+	/** Last pixel in the viewport at the top */
 	public double width;
-	/** < Last pixel on the right of the viewport in pixels */
+	/** Last pixel on the right of the viewport in pixels */
 	public double height;
 	public OSVR_ViewportDescription() {
 		super();
@@ -24,10 +24,10 @@ public class OSVR_ViewportDescription extends Structure {
 		return Arrays.asList("left", "lower", "width", "height");
 	}
 	/**
-	 * @param left < Left side of the viewport in pixels<br>
-	 * @param lower < First pixel in the viewport at the bottom.<br>
-	 * @param width < Last pixel in the viewport at the top<br>
-	 * @param height < Last pixel on the right of the viewport in pixels
+	 * @param left Left side of the viewport in pixels<br>
+	 * @param lower First pixel in the viewport at the bottom.<br>
+	 * @param width Last pixel in the viewport at the top<br>
+	 * @param height Last pixel on the right of the viewport in pixels
 	 */
 	public OSVR_ViewportDescription(double left, double lower, double width, double height) {
 		super();

jme3-vr/src/main/java/com/jme3/system/osvr/osvrrendermanageropengl/OSVR_OpenResultsOpenGL.java

@@ -24,7 +24,7 @@ public class OSVR_OpenResultsOpenGL extends Structure {
 		return Arrays.asList("status", "library", "buffers");
 	}
 	/**
-	 * @param status @see OSVR_OpenStatus<br>
+	 * @param status @see OsvrRenderManagerOpenGLLibrary.OSVR_OpenStatus <br>
 	 * C type : OSVR_OpenStatus<br>
 	 * @param library C type : OSVR_GraphicsLibraryOpenGL<br>
 	 * @param buffers C type : OSVR_RenderBufferOpenGL

jme3-vr/src/main/java/com/jme3/system/osvr/osvrrendermanageropengl/OSVR_ProjectionMatrix.java

@@ -13,7 +13,7 @@ public class OSVR_ProjectionMatrix extends Structure {
 	public double right;
 	public double top;
 	public double bottom;
-	/** < Cannot name "near" because Visual Studio keyword */
+	/** Cannot name "near" because Visual Studio keyword */
 	public double nearClip;
 	public double farClip;
 	public OSVR_ProjectionMatrix() {
@@ -22,7 +22,7 @@ public class OSVR_ProjectionMatrix extends Structure {
 	protected List<String> getFieldOrder() {
 		return Arrays.asList("left", "right", "top", "bottom", "nearClip", "farClip");
 	}
-	/** @param nearClip < Cannot name "near" because Visual Studio keyword */
+	/** @param nearClip Cannot name "near" because Visual Studio keyword */
 	public OSVR_ProjectionMatrix(double left, double right, double top, double bottom, double nearClip, double farClip) {
 		super();
 		this.left = left;

jme3-vr/src/main/java/com/jme3/system/osvr/osvrrendermanageropengl/OSVR_RenderParams.java

@@ -10,12 +10,12 @@ import java.util.List;
  */
 public class OSVR_RenderParams extends Structure {
 	/**
-	 * < Room space to insert<br>
+	 * Room space to insert<br>
 	 * C type : OSVR_PoseState*
 	 */
 	public Pointer worldFromRoomAppend;
 	/**
-	 * < Overrides head space<br>
+	 * Overrides head space<br>
 	 * C type : OSVR_PoseState*
 	 */
 	public Pointer roomFromHeadReplace;
@@ -28,9 +28,9 @@ public class OSVR_RenderParams extends Structure {
 		return Arrays.asList("worldFromRoomAppend", "roomFromHeadReplace", "nearClipDistanceMeters", "farClipDistanceMeters");
 	}
 	/**
-	 * @param worldFromRoomAppend < Room space to insert<br>
+	 * @param worldFromRoomAppend Room space to insert<br>
 	 * C type : OSVR_PoseState*<br>
-	 * @param roomFromHeadReplace < Overrides head space<br>
+	 * @param roomFromHeadReplace Overrides head space<br>
 	 * C type : OSVR_PoseState*
 	 */
 	public OSVR_RenderParams(Pointer worldFromRoomAppend, Pointer roomFromHeadReplace, double nearClipDistanceMeters, double farClipDistanceMeters) {

jme3-vr/src/main/java/com/jme3/system/osvr/osvrrendermanageropengl/OSVR_ViewportDescription.java

@@ -9,13 +9,13 @@ import java.util.List;
  * For help, please visit <a href="http://nativelibs4java.googlecode.com/">NativeLibs4Java</a> , <a href="http://rococoa.dev.java.net/">Rococoa</a>, or <a href="http://jna.dev.java.net/">JNA</a>.
  */
 public class OSVR_ViewportDescription extends Structure {
-	/** < Left side of the viewport in pixels */
+	/** Left side of the viewport in pixels */
 	public double left;
-	/** < First pixel in the viewport at the bottom. */
+	/** First pixel in the viewport at the bottom. */
 	public double lower;
-	/** < Last pixel in the viewport at the top */
+	/** Last pixel in the viewport at the top */
 	public double width;
-	/** < Last pixel on the right of the viewport in pixels */
+	/** Last pixel on the right of the viewport in pixels */
 	public double height;
 	public OSVR_ViewportDescription() {
 		super();
@@ -24,10 +24,10 @@ public class OSVR_ViewportDescription extends Structure {
 		return Arrays.asList("left", "lower", "width", "height");
 	}
 	/**
-	 * @param left < Left side of the viewport in pixels<br>
-	 * @param lower < First pixel in the viewport at the bottom.<br>
-	 * @param width < Last pixel in the viewport at the top<br>
-	 * @param height < Last pixel on the right of the viewport in pixels
+	 * @param left Left side of the viewport in pixels<br>
+	 * @param lower First pixel in the viewport at the bottom.<br>
+	 * @param width Last pixel in the viewport at the top<br>
+	 * @param height Last pixel on the right of the viewport in pixels
 	 */
 	public OSVR_ViewportDescription(double left, double lower, double width, double height) {
 		super();

jme3-vr/src/main/java/com/jme3/system/osvr/osvrtimevalue/OsvrTimeValueLibrary.java

@@ -73,7 +73,7 @@ public class OsvrTimeValueLibrary implements Library {
 	/**
 	 * Compares two time values (assumed to be normalized), returning
 	 * the same values as strcmp<br>
-	 * @return <0 if A is earlier than B, 0 if they are the same, and >0 if A<br>
+	 * @return &lt;0 if A is earlier than B, 0 if they are the same, and &gt;0 if A<br>
 	 * is later than B.<br>
 	 * Original signature : <code>int osvrTimeValueCmp(const OSVR_TimeValue*, const OSVR_TimeValue*)</code>
 	 */
@@ -95,17 +95,17 @@ public class OsvrTimeValueLibrary implements Library {
 	public static native byte osvrTimeValueGreater(OSVR_TimeValue tvA, OSVR_TimeValue tvB);
 	/**
 	 * Returns true if the time value is normalized. Typically used in assertions.<br>
-	 * Original signature : <code>bool osvrTimeValueIsNormalized(const OSVR_TimeValue&)</code>
+	 * Original signature : <code>bool osvrTimeValueIsNormalized(const OSVR_TimeValue&amp;)</code>
 	 */
 	public static native byte osvrTimeValueIsNormalized(OSVR_TimeValue tv);
 	/**
-	 * Operator > overload for time values<br>
-	 * Original signature : <code>bool operator>(const OSVR_TimeValue&, const OSVR_TimeValue&)</code>
+	 * Operator &gt; overload for time values<br>
+	 * Original signature : <code>bool operator&gt;(const OSVR_TimeValue&amp;, const OSVR_TimeValue&amp;)</code>
 	 */
 	public static native byte operatorGreater(OSVR_TimeValue tvA, OSVR_TimeValue tvB);
 	/**
 	 * Operator == overload for time values<br>
-	 * Original signature : <code>bool operator==(const OSVR_TimeValue&, const OSVR_TimeValue&)</code>
+	 * Original signature : <code>bool operator==(const OSVR_TimeValue&amp;, const OSVR_TimeValue&amp;)</code>
 	 */
 	public static native byte operatorIsEqual(OSVR_TimeValue tvA, OSVR_TimeValue tvB);
 	public static class timeval extends PointerType {

jme3-vr/src/main/java/test/TestInitHmd.java

@@ -37,7 +37,7 @@ import com.jme3.system.AppSettings;
 
 /**
  * Testing OpenVR environment.
- * @author Rickard <neph1 @ github>
+ * @author Rickard (neph1 @ github)
  */
 public class TestInitHmd {