Clean up the javadoc to pass java 8's doclint

By: Thinkofdeath <thinkofdeath@spigotmc.org>

paper-api/src/main/java/org/bukkit/plugin/PluginDescriptionFile.java

@@ -11,7 +11,6 @@ import java.util.Set;
 
 import org.bukkit.command.CommandExecutor;
 import org.bukkit.command.PluginCommand;
-import org.bukkit.plugin.Plugin;
 import org.bukkit.plugin.java.JavaPlugin;
 import org.bukkit.permissions.Permissible;
 import org.bukkit.permissions.Permission;
@@ -51,6 +50,7 @@ import com.google.common.collect.ImmutableSet;
  * This is a list of the possible yaml keys, with specific details included in
  * the respective method documentations:
  * <table border=1>
+ * <caption>The description of the plugin.yml layout</caption>
  * <tr>
  *     <th>Node</th>
  *     <th>Method</th>
@@ -400,7 +400,7 @@ public final class PluginDescriptionFile {
      *- feildmaster
      *- amaranth</pre></blockquote>
      * Is equivilant to this example:
-     * <blockquote><pre>authors: [Grum, feildmaster, aramanth]<pre></blockquote>
+     * <pre>authors: [Grum, feildmaster, aramanth]</pre>
      *
      * @return an immutable list of the plugin's authors
      */
@@ -560,6 +560,7 @@ public final class PluginDescriptionFile {
      * aliases</i>, can be defined at runtime using methods in {@link
      * PluginCommand} and are defined here only as a convenience.
      * <table border=1>
+     * <caption>The command section's description</caption>
      * <tr>
      *     <th>Node</th>
      *     <th>Method</th>
@@ -683,6 +684,7 @@ public final class PluginDescriptionFile {
      * <p>
      * A list of optional properties for permissions:
      * <table border=1>
+     * <caption>The permission section's description</caption>
      * <tr>
      *     <th>Node</th>
      *     <th>Description</th>
@@ -776,6 +778,8 @@ public final class PluginDescriptionFile {
      *</pre></blockquote>
      * Another example, with nested definitions, can be found <a
      * href="doc-files/permissions-example_plugin.yml">here</a>.
+     * 
+     * @return the permissions this plugin will register
      */
     public List<Permission> getPermissions() {
         if (permissions == null) {
@@ -817,7 +821,7 @@ public final class PluginDescriptionFile {
      * not included in the API. Any unrecognized
      * awareness (one unsupported or in a future version) will cause a dummy
      * object to be created instead of failing.
-     * <p>
+     * 
      * <ul>
      * <li>Currently only supports the enumerated values in {@link
      *     PluginAwareness.Flags}.
@@ -861,6 +865,7 @@ public final class PluginDescriptionFile {
     }
 
     /**
+     * @return unused
      * @deprecated unused
      */
     @Deprecated
@@ -1101,6 +1106,7 @@ public final class PluginDescriptionFile {
     }
 
     /**
+     * @return internal use
      * @deprecated Internal use
      */
     @Deprecated

paper-api/src/main/java/org/bukkit/plugin/TimedRegisteredListener.java

@@ -76,7 +76,7 @@ public class TimedRegisteredListener extends RegisteredListener {
      * returned, such that for any event this listener has handled,
      * <code>this.getEventClass().isAssignableFrom(event.getClass())</code>
      * and no class <code>this.getEventClass().isAssignableFrom(clazz)
-     * && this.getEventClass() != clazz &&
+     * {@literal && this.getEventClass() != clazz &&}
      * event.getClass().isAssignableFrom(clazz)</code> for all handled events.
      *
      * @return the event class handled by this RegisteredListener

paper-api/src/main/java/org/bukkit/plugin/java/JavaPlugin.java

@@ -72,6 +72,11 @@ public abstract class JavaPlugin extends PluginBase {
      *     PluginDescriptionFile, File, File) constructor} cannot be used.
      *     <p>
      *     Its existence may be temporary.
+     * @param loader the plugin loader
+     * @param server the server instance
+     * @param description the plugin's description
+     * @param dataFolder the plugin's data folder
+     * @param file the location of the plugin
      */
     @Deprecated
     protected JavaPlugin(final PluginLoader loader, final Server server, final PluginDescriptionFile description, final File dataFolder, final File file) {
@@ -321,6 +326,12 @@ public abstract class JavaPlugin extends PluginBase {
     }
 
     /**
+     * @param loader the plugin loader
+     * @param server the server instance
+     * @param description the plugin's description
+     * @param dataFolder the plugin's data folder
+     * @param file the location of the plugin
+     * @param classLoader the class loader
      * @deprecated This method is legacy and will be removed - it must be
      *     replaced by the specially provided constructor(s).
      */
@@ -492,6 +503,7 @@ public abstract class JavaPlugin extends PluginBase {
      * does not extend the class, where the intended plugin would have
      * resided in a different jar / classloader.
      *
+     * @param <T> a class that extends JavaPlugin
      * @param clazz the class desired
      * @return the plugin that provides and implements said class
      * @throws IllegalArgumentException if clazz is null
@@ -525,6 +537,8 @@ public abstract class JavaPlugin extends PluginBase {
      * This method provides fast access to the plugin that has provided the
      * given class.
      *
+     * @param clazz a class belonging to a plugin
+     * @return the plugin that provided the class
      * @throws IllegalArgumentException if the class is not provided by a
      *     JavaPlugin
      * @throws IllegalArgumentException if class is null

paper-api/src/main/java/org/bukkit/plugin/java/JavaPluginLoader.java

@@ -52,6 +52,8 @@ public final class JavaPluginLoader implements PluginLoader {
 
     /**
      * This class was not meant to be constructed explicitly
+     * 
+     * @param instance the server instance
      */
     @Deprecated
     public JavaPluginLoader(Server instance) {