Pulling all pending Bukkit-JavaDoc changes

A special thanks goes to @aerouk for almost all of the changes found here.

By: Wesley Wolfe <weswolf@aol.com>

paper-api/src/main/java/org/bukkit/scheduler/BukkitRunnable.java

@@ -33,10 +33,10 @@ public abstract class BukkitRunnable implements Runnable {
     }
 
     /**
-     * <b>Asynchronous tasks should never access any API in Bukkit.
-     *    Great care should be taken to assure the thread-safety of asynchronous tasks.</b>
-     * <br>
-     * <br>Schedules this in the Bukkit scheduler to run asynchronously.
+     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
+     * should be taken to assure the thread-safety of asynchronous tasks.</b>
+     * <p>
+     * Schedules this in the Bukkit scheduler to run asynchronously.
      *
      * @param plugin the reference to the plugin scheduling task
      * @return a BukkitTask that contains the id number
@@ -65,10 +65,11 @@ public abstract class BukkitRunnable implements Runnable {
     }
 
     /**
-     * <b>Asynchronous tasks should never access any API in Bukkit.
-     *    Great care should be taken to assure the thread-safety of asynchronous tasks.</b>
-     * <br>
-     * <br>Schedules this to run asynchronously after the specified number of server ticks.
+     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
+     * should be taken to assure the thread-safety of asynchronous tasks.</b>
+     * <p>
+     * Schedules this to run asynchronously after the specified number of
+     * server ticks.
      *
      * @param plugin the reference to the plugin scheduling task
      * @param delay the ticks to wait before running the task
@@ -83,7 +84,8 @@ public abstract class BukkitRunnable implements Runnable {
     }
 
     /**
-     * Schedules this to repeatedly run until cancelled, starting after the specified number of server ticks.
+     * Schedules this to repeatedly run until cancelled, starting after the
+     * specified number of server ticks.
      *
      * @param plugin the reference to the plugin scheduling task
      * @param delay the ticks to wait before running the task
@@ -99,18 +101,21 @@ public abstract class BukkitRunnable implements Runnable {
     }
 
     /**
-     * <b>Asynchronous tasks should never access any API in Bukkit.
-     *    Great care should be taken to assure the thread-safety of asynchronous tasks.</b>
-     * <br>
-     * <br>Schedules this to repeatedly run asynchronously until cancelled, starting after the specified number of server ticks.
+     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
+     * should be taken to assure the thread-safety of asynchronous tasks.</b>
+     * <p>
+     * Schedules this to repeatedly run asynchronously until cancelled,
+     * starting after the specified number of server ticks.
      *
      * @param plugin the reference to the plugin scheduling task
-     * @param delay the ticks to wait before running the task for the first time
+     * @param delay the ticks to wait before running the task for the first
+     *     time
      * @param period the ticks to wait between runs
      * @return a BukkitTask that contains the id number
      * @throws IllegalArgumentException if plugin is null
      * @throws IllegalStateException if this was already scheduled
-     * @see BukkitScheduler#runTaskTimerAsynchronously(Plugin, Runnable, long, long)
+     * @see BukkitScheduler#runTaskTimerAsynchronously(Plugin, Runnable, long,
+     *     long)
      */
     public synchronized BukkitTask runTaskTimerAsynchronously(Plugin plugin, long delay, long period) throws IllegalArgumentException, IllegalStateException  {
         checkState();

paper-api/src/main/java/org/bukkit/scheduler/BukkitScheduler.java

@@ -9,6 +9,7 @@ public interface BukkitScheduler {
 
     /**
      * Schedules a once off task to occur after a delay.
+     * <p>
      * This task will be executed by the main server thread.
      *
      * @param plugin Plugin that owns the task
@@ -20,6 +21,7 @@ public interface BukkitScheduler {
 
     /**
      * Schedules a once off task to occur as soon as possible.
+     * <p>
      * This task will be executed by the main server thread.
      *
      * @param plugin Plugin that owns the task
@@ -30,6 +32,7 @@ public interface BukkitScheduler {
 
     /**
      * Schedules a repeating task.
+     * <p>
      * This task will be executed by the main server thread.
      *
      * @param plugin Plugin that owns the task
@@ -41,60 +44,65 @@ public interface BukkitScheduler {
     public int scheduleSyncRepeatingTask(Plugin plugin, Runnable task, long delay, long period);
 
     /**
-     * <b>Asynchronous tasks should never access any API in Bukkit.
-     *    Great care should be taken to assure the thread-safety of asynchronous tasks.</b>
-     * <br>
-     * <br>Schedules a once off task to occur after a delay.
-     * This task will be executed by a thread managed by the scheduler.
+     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
+     * should be taken to assure the thread-safety of asynchronous tasks.</b>
+     * <p>
+     * Schedules a once off task to occur after a delay. This task will be
+     * executed by a thread managed by the scheduler.
      *
      * @param plugin Plugin that owns the task
      * @param task Task to be executed
      * @param delay Delay in server ticks before executing task
      * @return Task id number (-1 if scheduling failed)
-     * @deprecated This name is misleading, as it does not schedule "a sync" task, but rather, "an async" task
+     * @deprecated This name is misleading, as it does not schedule "a sync"
+     *     task, but rather, "an async" task
      */
     @Deprecated
     public int scheduleAsyncDelayedTask(Plugin plugin, Runnable task, long delay);
 
     /**
-     * <b>Asynchronous tasks should never access any API in Bukkit.
-     *    Great care should be taken to assure the thread-safety of asynchronous tasks.</b>
-     * <br>
-     * <br>Schedules a once off task to occur as soon as possible.
-     * This task will be executed by a thread managed by the scheduler.
+     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
+     * should be taken to assure the thread-safety of asynchronous tasks.</b>
+     * <p>
+     * Schedules a once off task to occur as soon as possible. This task will
+     * be executed by a thread managed by the scheduler.
      *
      * @param plugin Plugin that owns the task
      * @param task Task to be executed
      * @return Task id number (-1 if scheduling failed)
-     * @deprecated This name is misleading, as it does not schedule "a sync" task, but rather, "an async" task
+     * @deprecated This name is misleading, as it does not schedule "a sync"
+     *     task, but rather, "an async" task
      */
     @Deprecated
     public int scheduleAsyncDelayedTask(Plugin plugin, Runnable task);
 
     /**
-     * <b>Asynchronous tasks should never access any API in Bukkit.
-     *    Great care should be taken to assure the thread-safety of asynchronous tasks.</b>
-     * <br>
-     * <br>Schedules a repeating task.
-     * This task will be executed by a thread managed by the scheduler.
+     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
+     * should be taken to assure the thread-safety of asynchronous tasks.</b>
+     * <p>
+     * Schedules a repeating task. This task will be executed by a thread
+     * managed by the scheduler.
      *
      * @param plugin Plugin that owns the task
      * @param task Task to be executed
      * @param delay Delay in server ticks before executing first repeat
      * @param period Period in server ticks of the task
      * @return Task id number (-1 if scheduling failed)
-     * @deprecated This name is misleading, as it does not schedule "a sync" task, but rather, "an async" task
+     * @deprecated This name is misleading, as it does not schedule "a sync"
+     *     task, but rather, "an async" task
      */
     @Deprecated
     public int scheduleAsyncRepeatingTask(Plugin plugin, Runnable task, long delay, long period);
 
     /**
-     * Calls a method on the main thread and returns a Future object
-     * This task will be executed by the main server thread.
-     * <p>
-     * Note: The Future.get() methods must NOT be called from the main thread.
-     * Note2: There is at least an average of 10ms latency until the isDone() method returns true.
-     *
+     * Calls a method on the main thread and returns a Future object. This
+     * task will be executed by the main server thread.
+     * <ul>
+     * <li>Note: The Future.get() methods must NOT be called from the main
+     *     thread.
+     * <li>Note2: There is at least an average of 10ms latency until the
+     *     isDone() method returns true.
+     * </ul>
      * @param <T> The callable's return type
      * @param plugin Plugin that owns the task
      * @param task Task to be executed
@@ -110,7 +118,8 @@ public interface BukkitScheduler {
     public void cancelTask(int taskId);
 
     /**
-     * Removes all tasks associated with a particular plugin from the scheduler.
+     * Removes all tasks associated with a particular plugin from the
+     * scheduler.
      *
      * @param plugin Owner of tasks to be removed
      */
@@ -124,10 +133,12 @@ public interface BukkitScheduler {
     /**
      * Check if the task currently running.
      * <p>
-     * A repeating task might not be running currently, but will be running in the future.
-     * A task that has finished, and does not repeat, will not be running ever again.
+     * A repeating task might not be running currently, but will be running in
+     * the future. A task that has finished, and does not repeat, will not be
+     * running ever again.
      * <p>
-     * Explicitly, a task is running if there exists a thread for it, and that thread is alive.
+     * Explicitly, a task is running if there exists a thread for it, and that
+     * thread is alive.
      *
      * @param taskId The task to check.
      * <p>
@@ -138,8 +149,9 @@ public interface BukkitScheduler {
     /**
      * Check if the task queued to be run later.
      * <p>
-     * If a repeating task is currently running, it might not be queued now but could be in the future.
-     * A task that is not queued, and not running, will not be queued again.
+     * If a repeating task is currently running, it might not be queued now
+     * but could be in the future. A task that is not queued, and not running,
+     * will not be queued again.
      *
      * @param taskId The task to check.
      * <p>
@@ -150,14 +162,16 @@ public interface BukkitScheduler {
     /**
      * Returns a list of all active workers.
      * <p>
-     * This list contains asynch tasks that are being executed by separate threads.
+     * This list contains asynch tasks that are being executed by separate
+     * threads.
      *
      * @return Active workers
      */
     public List<BukkitWorker> getActiveWorkers();
 
     /**
-     * Returns a list of all pending tasks. The ordering of the tasks is not related to their order of execution.
+     * Returns a list of all pending tasks. The ordering of the tasks is not
+     * related to their order of execution.
      *
      * @return Active workers
      */
@@ -175,10 +189,10 @@ public interface BukkitScheduler {
     public BukkitTask runTask(Plugin plugin, Runnable task) throws IllegalArgumentException;
 
     /**
-     * <b>Asynchronous tasks should never access any API in Bukkit.
-     *    Great care should be taken to assure the thread-safety of asynchronous tasks.</b>
-     * <br>
-     * <br>Returns a task that will run asynchronously.
+     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
+     * should be taken to assure the thread-safety of asynchronous tasks.</b>
+     * <p>
+     * Returns a task that will run asynchronously.
      *
      * @param plugin the reference to the plugin scheduling task
      * @param task the task to be run
@@ -189,7 +203,8 @@ public interface BukkitScheduler {
     public BukkitTask runTaskAsynchronously(Plugin plugin, Runnable task) throws IllegalArgumentException;
 
     /**
-     * Returns a task that will run after the specified number of server ticks.
+     * Returns a task that will run after the specified number of server
+     * ticks.
      *
      * @param plugin the reference to the plugin scheduling task
      * @param task the task to be run
@@ -201,10 +216,11 @@ public interface BukkitScheduler {
     public BukkitTask runTaskLater(Plugin plugin, Runnable task, long delay) throws IllegalArgumentException;
 
     /**
-     * <b>Asynchronous tasks should never access any API in Bukkit.
-     *    Great care should be taken to assure the thread-safety of asynchronous tasks.</b>
-     * <br>
-     * <br>Returns a task that will run asynchronously after the specified number of server ticks.
+     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
+     * should be taken to assure the thread-safety of asynchronous tasks.</b>
+     * <p>
+     * Returns a task that will run asynchronously after the specified number
+     * of server ticks.
      *
      * @param plugin the reference to the plugin scheduling task
      * @param task the task to be run
@@ -216,7 +232,8 @@ public interface BukkitScheduler {
     public BukkitTask runTaskLaterAsynchronously(Plugin plugin, Runnable task, long delay) throws IllegalArgumentException;
 
     /**
-     * Returns a task that will repeatedly run until cancelled, starting after the specified number of server ticks.
+     * Returns a task that will repeatedly run until cancelled, starting after
+     * the specified number of server ticks.
      *
      * @param plugin the reference to the plugin scheduling task
      * @param task the task to be run
@@ -229,14 +246,16 @@ public interface BukkitScheduler {
     public BukkitTask runTaskTimer(Plugin plugin, Runnable task, long delay, long period) throws IllegalArgumentException;
 
     /**
-     * <b>Asynchronous tasks should never access any API in Bukkit.
-     *    Great care should be taken to assure the thread-safety of asynchronous tasks.</b>
-     * <br>
-     * <br>Returns a task that will repeatedly run asynchronously until cancelled, starting after the specified number of server ticks.
+     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
+     * should be taken to assure the thread-safety of asynchronous tasks.</b>
+     * <p>
+     * Returns a task that will repeatedly run asynchronously until cancelled,
+     * starting after the specified number of server ticks.
      *
      * @param plugin the reference to the plugin scheduling task
      * @param task the task to be run
-     * @param delay the ticks to wait before running the task for the first time
+     * @param delay the ticks to wait before running the task for the first
+     *     time
      * @param period the ticks to wait between runs
      * @return a BukkitTask that contains the id number
      * @throws IllegalArgumentException if plugin is null

paper-api/src/main/java/org/bukkit/scheduler/BukkitWorker.java

@@ -5,7 +5,7 @@ import org.bukkit.plugin.Plugin;
 /**
  * Represents a worker thread for the scheduler. This gives information about
  * the Thread object for the task, owner of the task and the taskId.
- * </p>
+ * <p>
  * Workers are used to execute async tasks.
  */
 public interface BukkitWorker {