Javadoc Warning Cleanup (OpenJDK 9+)

[louhy]

Any interest in cleaning up Javadoc warnings?

> Task :jme3-jbullet:javadoc
/home/lou/git/jmonkeyengine/jme3-jbullet/src/main/java/com/jme3/bullet/PhysicsSpace.java:791: warning - invalid usage of tag >
/home/lou/git/jmonkeyengine/jme3-jbullet/src/main/java/com/jme3/bullet/PhysicsSpace.java:807: warning - invalid usage of tag >
/home/lou/git/jmonkeyengine/jme3-jbullet/src/main/java/com/jme3/bullet/PhysicsSpace.java:791: warning - invalid usage of tag >
/home/lou/git/jmonkeyengine/jme3-jbullet/src/main/java/com/jme3/bullet/PhysicsSpace.java:807: warning - invalid usage of tag >
/home/lou/git/jmonkeyengine/jme3-jbullet/src/main/java/com/jme3/bullet/PhysicsSpace.java:920: warning - invalid usage of tag &
/home/lou/git/jmonkeyengine/jme3-jbullet/src/main/java/com/jme3/bullet/objects/PhysicsVehicle.java:304: warning - invalid usage of tag &
/home/lou/git/jmonkeyengine/jme3-jbullet/src/main/java/com/jme3/bullet/objects/PhysicsVehicle.java:315: warning - invalid usage of tag &
/home/lou/git/jmonkeyengine/jme3-jbullet/src/main/java/com/jme3/bullet/objects/VehicleWheel.java:181: warning - invalid usage of tag &
/home/lou/git/jmonkeyengine/jme3-jbullet/src/main/java/com/jme3/bullet/PhysicsSpace.java:791: warning - invalid usage of tag >
/home/lou/git/jmonkeyengine/jme3-jbullet/src/main/java/com/jme3/bullet/PhysicsSpace.java:807: warning - invalid usage of tag >
/home/lou/git/jmonkeyengine/jme3-jbullet/src/main/java/com/jme3/bullet/PhysicsSpace.java:807: warning - invalid usage of tag >
/home/lou/git/jmonkeyengine/jme3-jbullet/src/main/java/com/jme3/bullet/PhysicsSpace.java:791: warning - invalid usage of tag >
/home/lou/git/jmonkeyengine/jme3-jbullet/src/main/java/com/jme3/bullet/PhysicsSpace.java:807: warning - invalid usage of tag >
/home/lou/git/jmonkeyengine/jme3-jbullet/src/main/java/com/jme3/bullet/PhysicsSpace.java:791: warning - invalid usage of tag >
/home/lou/git/jmonkeyengine/jme3-jbullet/src/main/java/com/jme3/bullet/PhysicsSpace.java:807: warning - invalid usage of tag >
15 warnings

Most of these are just warnings cluttering up build logs, but I also want to note that something in jme3-vr actually causes javadoc to crash with OpenJDK 11:

> Task :jme3-vr:javadoc
javadoc: error - An internal exception has occurred. 
        (java.lang.NullPointerException)
Please file a bug against the javadoc tool via the Java bug reporting page
(http://bugreport.java.com) after checking the Bug Database (http://bugs.java.com)
for duplicates. Include error messages and the following diagnostic in your report. Thank you.
java.lang.NullPointerException
        at jdk.compiler/com.sun.tools.javac.api.JavacTrees.attributeDocReference(JavacTrees.java:454)
        at jdk.compiler/com.sun.tools.javac.api.JavacTrees.getElement(JavacTrees.java:414)
        at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.util.CommentHelper.getElement(CommentHelper.java:179)
        at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.util.CommentHelper$3.visitReference(CommentHelper.java:460)
        at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.util.CommentHelper$3.visitReference(CommentHelper.java:434)

I can continue cleaning these up globally, if there's interest. Good way to randomly explore things, since you kinda have to read the doc to ensure the change still makes sense.

[stephengold]

I'm in favor of cleaning up Javadoc warnings.

[stephengold]

Is this issue resolved yet?

[louhy]

For JBullet yes, but there's more to be fixed, especially in vr, so there's more coming. I'll close it out when done, or you can close if you want.

It'll take a little time because we can't just do a find/replace of characters like < or &. The comments really need to be read to make sure the replacement makes sense. I think I noticed VR even using < sometimes like an ascii "arrow" <----, so it's not just find and replace with "less than".

[louhy]

Cleanup about done (JDK11 and 8 build output below). Much better now!
PR which fixes Javadoc NPE crash in JDK 11 coming shortly...

Nasty one which will need to be addressed eventually (out of scope for this cleanup):

• Illegal reflective access by com.jme3.util.ReflectionAllocator

Others, not sure if it's worth the effort addressing yet?

• ...uses unchecked or unsafe operations.
• ...uses or overrides a deprecated API.

lou@m1 ~/git/jmonkeyengine $ gradle clean build

> Configure project :
Full Version: 3.3-vr-javadoc-cleanup-6833
POM Version: 3.3.0-vr-javadoc-cleanup-SNAPSHOT

> Task :jme3-core:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-plugins:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-android:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: /home/lou/git/jmonkeyengine/jme3-android/src/main/java/com/jme3/input/android/AndroidJoystickJoyInput14.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-desktop:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-blender:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.

> Task :jme3-terrain:compileJava
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-bullet:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-bullet:generateNativeHeaders
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-core:compileTestJava
Note: /home/lou/git/jmonkeyengine/jme3-core/src/test/java/com/jme3/cinematic/CinematicTest.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: /home/lou/git/jmonkeyengine/jme3-core/src/test/java/com/jme3/material/plugins/J3MLoaderTest.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-core:test
WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by com.jme3.util.ReflectionAllocator (file:/home/lou/git/jmonkeyengine/jme3-core/build/classes/java/main/) to method sun.nio.ch.DirectBuffer.cleaner()
WARNING: Please consider reporting this to the maintainers of com.jme3.util.ReflectionAllocator
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release

> Task :jme3-jbullet:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-jogg:compileJava
Note: /home/lou/git/jmonkeyengine/jme3-jogg/src/main/java/com/jme3/audio/plugins/OGGLoader.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-jogl:compileJava
Note: /home/lou/git/jmonkeyengine/jme3-jogl/src/main/java/com/jme3/system/jogl/JoglContext.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.

> Task :jme3-lwjgl:compileJava
Note: /home/lou/git/jmonkeyengine/jme3-lwjgl/src/main/java/com/jme3/system/lwjgl/LwjglContext.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.

> Task :jme3-networking:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-niftygui:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.

> Task :jme3-examples:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-lwjgl3:compileJava
Note: /home/lou/git/jmonkeyengine/jme3-lwjgl3/src/main/java/com/jme3/system/lwjgl/LwjglContext.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: /home/lou/git/jmonkeyengine/jme3-lwjgl3/src/main/java/com/jme3/system/lwjgl/LwjglContext.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-plugins:test
WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by com.jme3.util.ReflectionAllocator (file:/home/lou/git/jmonkeyengine/jme3-core/build/libs/jme3-core-3.3.0-vr-javadoc-cleanup-SNAPSHOT.jar) to method sun.nio.ch.DirectBuffer.cleaner()
WARNING: Please consider reporting this to the maintainers of com.jme3.util.ReflectionAllocator
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release

> Task :jme3-vr:compileJava
Note: /home/lou/git/jmonkeyengine/jme3-vr/src/main/java/com/jme3/input/vr/openvr/OpenVR.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.

BUILD SUCCESSFUL in 1m 9s
170 actionable tasks: 167 executed, 3 up-to-date
lou@m1 ~/git/jmonkeyengine $ java -version
openjdk version "11.0.2" 2019-01-15
OpenJDK Runtime Environment 18.9 (build 11.0.2+9)
OpenJDK 64-Bit Server VM 18.9 (build 11.0.2+9, mixed mode)

lou@m1 ~/git/jmonkeyengine $ gradle clean build

> Configure project :
Full Version: 3.3-vr-javadoc-cleanup-6835
POM Version: 3.3.0-vr-javadoc-cleanup-SNAPSHOT

> Task :jme3-core:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-plugins:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-android:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: /home/lou/git/jmonkeyengine/jme3-android/src/main/java/com/jme3/input/android/AndroidJoystickJoyInput14.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-desktop:compileJava
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-blender:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.

> Task :jme3-terrain:compileJava
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-bullet:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-bullet:generateNativeHeaders
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-core:compileTestJava
Note: /home/lou/git/jmonkeyengine/jme3-core/src/test/java/com/jme3/cinematic/CinematicTest.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: /home/lou/git/jmonkeyengine/jme3-core/src/test/java/com/jme3/material/plugins/J3MLoaderTest.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-jbullet:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-jogg:compileJava
Note: /home/lou/git/jmonkeyengine/jme3-jogg/src/main/java/com/jme3/audio/plugins/OGGLoader.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-networking:compileJava
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-niftygui:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.

> Task :jme3-examples:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-lwjgl3:compileJava
Note: /home/lou/git/jmonkeyengine/jme3-lwjgl3/src/main/java/com/jme3/system/lwjgl/LwjglContext.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :jme3-vr:compileJava
Note: /home/lou/git/jmonkeyengine/jme3-vr/src/main/java/com/jme3/input/vr/openvr/OpenVR.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.

BUILD SUCCESSFUL in 57s
170 actionable tasks: 168 executed, 2 up-to-date
lou@m1 ~/git/jmonkeyengine $ java -version
openjdk version "1.8.0_212"
OpenJDK Runtime Environment (AdoptOpenJDK)(build 1.8.0_212-b03)
OpenJDK 64-Bit Server VM (AdoptOpenJDK)(build 25.212-b03, mixed mode)

[tlf30]

@louhy we do not need to worry about the Illegal reflective access by com.jme3.util.ReflectionAllocator as this is a JDK 11 warning. In some future (undisclosed?) jdk, reflection will be disable unless explicitly allowed by the module definition upon which the class that the reflection is acting upon resides in.

Also huge THANK YOU! for cleaning up the javadocs

[louhy]

No problem, turned out to be a fun random way to explore the repo. 😆

Agree on the reflective warning, just hopefully there'll be a solution in place by the time that warning turns to error. Nice thing about getting rid of the "dumb" warnings is that these little leftovers which may require more thought will be visible.

[louhy]

Closing this since it's 99% better now. I'd be happy to help out if anyone wants to tackle the remaining few warnings, but for now I'm satisfied with output.