#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();

paper-api/src/main/java/org/bukkit/generator/BlockPopulator.java

@@ -3,6 +3,7 @@ package org.bukkit.generator;
 import java.util.Random;
 import org.bukkit.Chunk;
 import org.bukkit.World;
+import org.bukkit.event.world.WorldInitEvent;
 import org.jetbrains.annotations.NotNull;
 
 /**
@@ -10,6 +11,13 @@ import org.jetbrains.annotations.NotNull;
  * <p>
  * For example, generating glowstone inside the nether or generating dungeons
  * full of treasure
+ * <p>
+ * A BlockPopulator can be used in combination with a custom {@link ChunkGenerator}
+ * by returning it in the method {@link ChunkGenerator#getDefaultPopulators(World)}
+ * or by adding it manually to the worlds populator list returned by {@link World#getPopulators()}.
+ * <p>
+ * When adding a BlockPopulator manually to a world it is recommended to do so during
+ * the {@link WorldInitEvent}.
  */
 public abstract class BlockPopulator {
 
@@ -54,10 +62,10 @@ public abstract class BlockPopulator {
      *
      * @param worldInfo The world info of the world to generate in
      * @param random The random generator to use
-     * @param x The X-coordinate of the chunk
-     * @param z The Z-coordinate of the chunk
+     * @param chunkX The X-coordinate of the chunk
+     * @param chunkZ The Z-coordinate of the chunk
      * @param limitedRegion The chunk region to populate
      */
-    public void populate(@NotNull WorldInfo worldInfo, @NotNull Random random, int x, int z, @NotNull LimitedRegion limitedRegion) {
+    public void populate(@NotNull WorldInfo worldInfo, @NotNull Random random, int chunkX, int chunkZ, @NotNull LimitedRegion limitedRegion) {
     }
 }

paper-api/src/main/java/org/bukkit/generator/ChunkGenerator.java

@@ -73,11 +73,11 @@ public abstract class ChunkGenerator {
      *
      * @param worldInfo The world info of the world this chunk will be used for
      * @param random The random generator to use
-     * @param x The X-coordinate of the chunk
-     * @param z The Z-coordinate of the chunk
+     * @param chunkX The X-coordinate of the chunk
+     * @param chunkZ The Z-coordinate of the chunk
      * @param chunkData To modify
      */
-    public void generateNoise(@NotNull WorldInfo worldInfo, @NotNull Random random, int x, int z, @NotNull ChunkData chunkData) {
+    public void generateNoise(@NotNull WorldInfo worldInfo, @NotNull Random random, int chunkX, int chunkZ, @NotNull ChunkData chunkData) {
     }
 
     /**
@@ -100,11 +100,11 @@ public abstract class ChunkGenerator {
      *
      * @param worldInfo The world info of the world this chunk will be used for
      * @param random The random generator to use
-     * @param x The X-coordinate of the chunk
-     * @param z The Z-coordinate of the chunk
+     * @param chunkX The X-coordinate of the chunk
+     * @param chunkZ The Z-coordinate of the chunk
      * @param chunkData To modify
      */
-    public void generateSurface(@NotNull WorldInfo worldInfo, @NotNull Random random, int x, int z, @NotNull ChunkData chunkData) {
+    public void generateSurface(@NotNull WorldInfo worldInfo, @NotNull Random random, int chunkX, int chunkZ, @NotNull ChunkData chunkData) {
     }
 
     /**
@@ -127,11 +127,11 @@ public abstract class ChunkGenerator {
      *
      * @param worldInfo The world info of the world this chunk will be used for
      * @param random The random generator to use
-     * @param x The X-coordinate of the chunk
-     * @param z The Z-coordinate of the chunk
+     * @param chunkX The X-coordinate of the chunk
+     * @param chunkZ The Z-coordinate of the chunk
      * @param chunkData To modify
      */
-    public void generateBedrock(@NotNull WorldInfo worldInfo, @NotNull Random random, int x, int z, @NotNull ChunkData chunkData) {
+    public void generateBedrock(@NotNull WorldInfo worldInfo, @NotNull Random random, int chunkX, int chunkZ, @NotNull ChunkData chunkData) {
     }
 
     /**
@@ -154,11 +154,11 @@ public abstract class ChunkGenerator {
      *
      * @param worldInfo The world info of the world this chunk will be used for
      * @param random The random generator to use
-     * @param x The X-coordinate of the chunk
-     * @param z The Z-coordinate of the chunk
+     * @param chunkX The X-coordinate of the chunk
+     * @param chunkZ The Z-coordinate of the chunk
      * @param chunkData To modify
      */
-    public void generateCaves(@NotNull WorldInfo worldInfo, @NotNull Random random, int x, int z, @NotNull ChunkData chunkData) {
+    public void generateCaves(@NotNull WorldInfo worldInfo, @NotNull Random random, int chunkX, int chunkZ, @NotNull ChunkData chunkData) {
     }
 
     /**
@@ -289,12 +289,12 @@ public abstract class ChunkGenerator {
      *     generator
      * @return ChunkData containing the types for each block created by this
      *     generator
-     * @deprecated The generation is now split up
+     * @deprecated The generation is now split up and the new methods should be used, see {@link ChunkGenerator}
      */
     @NotNull
     @Deprecated
     public ChunkData generateChunkData(@NotNull World world, @NotNull Random random, int x, int z, @NotNull BiomeGrid biome) {
-        throw new UnsupportedOperationException("Custom generator " + getClass().getName() + " is missing required method generateChunkData");
+        throw new UnsupportedOperationException("Not implemented, no longer needed");
     }
 
     /**