#749: Various javadoc improvements

By: DerFrZocker <derrieple@gmail.com>

paper-api/src/main/java/org/bukkit/event/EventPriority.java

@@ -1,12 +1,18 @@
 package org.bukkit.event;
 
 /**
- * Represents an event's priority in execution
+ * Represents an event's priority in execution.
+ * <p>
+ * Listeners with lower priority are called first
+ * will listeners with higher priority are called last.
+ * <p>
+ * Listeners are called in following order:
+ * {@link #LOWEST} -> {@link #LOW} -> {@link #NORMAL} -> {@link #HIGH} -> {@link #HIGHEST} -> {@link #MONITOR}
  */
 public enum EventPriority {
 
     /**
-     * Event call is of very low importance and should be ran first, to allow
+     * Event call is of very low importance and should be run first, to allow
      * other plugins to further customise the outcome
      */
     LOWEST(0),
@@ -15,7 +21,7 @@ public enum EventPriority {
      */
     LOW(1),
     /**
-     * Event call is neither important nor unimportant, and may be ran
+     * Event call is neither important nor unimportant, and may be run
      * normally
      */
     NORMAL(2),

paper-api/src/main/java/org/bukkit/event/block/BlockDamageAbortEvent.java

@@ -8,6 +8,7 @@ import org.jetbrains.annotations.NotNull;
 
 /**
  * Called when a player stops damaging a Block.
+ * @see BlockDamageEvent
  */
 public class BlockDamageAbortEvent extends BlockEvent {
 

paper-api/src/main/java/org/bukkit/event/block/BlockDamageEvent.java

@@ -11,6 +11,7 @@ import org.jetbrains.annotations.NotNull;
  * Called when a block is damaged by a player.
  * <p>
  * If a Block Damage event is cancelled, the block will not be damaged.
+ * @see BlockDamageAbortEvent
  */
 public class BlockDamageEvent extends BlockEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();

paper-api/src/main/java/org/bukkit/event/entity/EntityToggleGlideEvent.java

@@ -35,6 +35,12 @@ public class EntityToggleGlideEvent extends EntityEvent implements Cancellable {
         this.cancel = cancel;
     }
 
+    /**
+     * Returns true if the entity is now gliding or
+     * false if the entity stops gliding.
+     *
+     * @return new gliding state
+     */
     public boolean isGliding() {
         return isGliding;
     }

paper-api/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java

@@ -29,6 +29,12 @@ public class EntityToggleSwimEvent extends EntityEvent implements Cancellable {
         this.cancel = cancel;
     }
 
+    /**
+     * Returns true if the entity is now swims or
+     * false if the entity stops swimming.
+     *
+     * @return new swimming state
+     */
     public boolean isSwimming() {
         return isSwimming;
     }

paper-api/src/main/java/org/bukkit/event/player/PlayerKickEvent.java

@@ -12,7 +12,7 @@ public class PlayerKickEvent extends PlayerEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
     private String leaveMessage;
     private String kickReason;
-    private Boolean cancel;
+    private boolean cancel;
 
     public PlayerKickEvent(@NotNull final Player playerKicked, @NotNull final String kickReason, @NotNull final String leaveMessage) {
         super(playerKicked);

paper-api/src/main/java/org/bukkit/event/world/ChunkLoadEvent.java

@@ -2,6 +2,7 @@ package org.bukkit.event.world;
 
 import org.bukkit.Chunk;
 import org.bukkit.event.HandlerList;
+import org.bukkit.generator.BlockPopulator;
 import org.jetbrains.annotations.NotNull;
 
 /**
@@ -19,7 +20,8 @@ public class ChunkLoadEvent extends ChunkEvent {
     /**
      * Gets if this chunk was newly created or not.
      * <p>
-     * Note that if this chunk is new, it will not be populated at this time.
+     * <b>Note:</b> Do not use this to generated blocks in a newly generated chunk.
+     * Use a {@link BlockPopulator} instead.
      *
      * @return true if the chunk is new, otherwise false
      */

paper-api/src/main/java/org/bukkit/event/world/ChunkPopulateEvent.java

@@ -6,10 +6,10 @@ import org.bukkit.generator.BlockPopulator;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Thrown when a new chunk has finished being populated.
+ * Thrown when a newly generated chunk has finished being populated.
  * <p>
- * If your intent is to populate the chunk using this event, please see {@link
- * BlockPopulator}
+ * <b>Note:</b> Do not use this to generated blocks in a newly generated chunk.
+ * Use a {@link BlockPopulator} instead.
  */
 public class ChunkPopulateEvent extends ChunkEvent {
     private static final HandlerList handlers = new HandlerList();

paper-api/src/main/java/org/bukkit/event/world/WorldInitEvent.java

@@ -5,7 +5,10 @@ import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called when a World is initializing
+ * Called when a World is initializing.
+ * <p>
+ * To get every world it is recommended to add following to the plugin.yml.
+ * <pre>load: STARTUP</pre>
  */
 public class WorldInitEvent extends WorldEvent {
     private static final HandlerList handlers = new HandlerList();