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

[louhy]

Fixes 100+ Javadoc warnings in JDK 11 and this Javadoc NPE:

> 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.

> Task :jme3-vr:processResources
> Task :jme3-vr:classes
> Task :jme3-vr:jar

> 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)
	at jdk.compiler/com.sun.tools.javac.tree.DCTree$DCReference.accept(DCTree.java:669)
	at jdk.compiler/com.sun.source.util.SimpleDocTreeVisitor.visit(SimpleDocTreeVisitor.java:79)
	at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.util.CommentHelper$3.visitSee(CommentHelper.java:438)
	at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.util.CommentHelper$3.visitSee(CommentHelper.java:434)
	at jdk.compiler/com.sun.tools.javac.tree.DCTree$DCSee.accept(DCTree.java:715)
	at jdk.compiler/com.sun.source.util.SimpleDocTreeVisitor.visit(SimpleDocTreeVisitor.java:79)
	at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.util.CommentHelper.getReferencedElement(CommentHelper.java:477)
	at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.util.CommentHelper.getReferencedClass(CommentHelper.java:366)
	at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.HtmlDocletWriter.seeTagToContent(HtmlDocletWriter.java:999)
	at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.TagletWriterImpl.seeTagOutput(TagletWriterImpl.java:279)
	at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.taglets.SeeTaglet.getTagletOutput(SeeTaglet.java:84)
	at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.taglets.TagletWriter.genTagOutput(TagletWriter.java:242)
	at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.HtmlDocletWriter.addTagsInfo(HtmlDocletWriter.java:332)
	at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.ConstructorWriterImpl.addTags(ConstructorWriterImpl.java:191)
	at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.builders.ConstructorBuilder.buildTagInfo(ConstructorBuilder.java:195)
	at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.builders.ConstructorBuilder.buildConstructorDoc(ConstructorBuilder.java:149)
	at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.builders.ConstructorBuilder.build(ConstructorBuilder.java:124)
	at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.builders.ClassBuilder.buildConstructorDetails(ClassBuilder.java:383)
	at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.builders.ClassBuilder.buildMemberDetails(ClassBuilder.java:340)
	at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.builders.ClassBuilder.buildClassDoc(ClassBuilder.java:145)
	at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.builders.ClassBuilder.build(ClassBuilder.java:120)
	at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.HtmlDoclet.generateClassFiles(HtmlDoclet.java:266)
	at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.AbstractDoclet.generateClassFiles(AbstractDoclet.java:286)
	at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.AbstractDoclet.generateClassFiles(AbstractDoclet.java:268)
	at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.AbstractDoclet.startGeneration(AbstractDoclet.java:207)
	at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.AbstractDoclet.run(AbstractDoclet.java:114)
	at jdk.javadoc/jdk.javadoc.doclet.StandardDoclet.run(StandardDoclet.java:72)
	at jdk.javadoc/jdk.javadoc.internal.tool.Start.parseAndExecute(Start.java:582)
	at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:431)
	at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:344)
	at jdk.javadoc/jdk.javadoc.internal.tool.Main.execute(Main.java:63)
	at jdk.javadoc/jdk.javadoc.internal.tool.Main.main(Main.java:52)
1 error

[stephengold]

Did you check the NPE against bugs.java.com?

[stephengold]

I think this PR is okay to integrate, but I'd like to leave it open for a week in case someone else will review it.

While the purpose of this PR is to cleanup javadoc diagnostic messages, it should be noted that (unlike previous javadoc PRs) this one changes more than just comments; it deprecates classes and methods that weren't actually deprecated before.

[louhy]

Did you check the NPE against bugs.java.com?

Actually I did do some poking around a few weeks ago when I saw this, and I found something that looked like a match. Apparently it's fixed in JDK 12, that's how I was able to pinpoint the source of the crash/warnings. Probably this is what I found: https://bugs.openjdk.java.net/browse/JDK-8181854
Different version, but maybe it made it to 11 due to this rapid fire release cycle.

Yeah, the deprecated annotations were added based on the @ deprecated in the comments (which were of course the source of the warnings here), so I agree it's a good idea to take a closer look to make sure the comments were correct. If not the fix will just be inverted to avoid the warnings, no big deal.

[stephengold]

On 2nd thought, perhaps we should avoid deprecating methods in dot-dot releases.