More JavaDoc improvements.

By: EvilSeph <evilseph@gmail.com>

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

@@ -5,7 +5,13 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
 
 /**
- * Called when a block is broken by a player
+ * Called when a block is broken by a player.
+ *<p />
+ * Note:
+ * Plugins wanting to simulate a traditional block drop should set the block to air and utilise their own methods for determining
+ *   what the default drop for the block being broken is and what to do about it, if anything.
+ *<p />
+ * If a Block Break event is cancelled, the block will not break.
  */
 public class BlockBreakEvent extends BlockEvent implements Cancellable {
 
@@ -19,9 +25,9 @@ public class BlockBreakEvent extends BlockEvent implements Cancellable {
     }
 
     /**
-     * Gets the Player that is breaking the block
+     * Gets the Player that is breaking the block involved in this event.
      *
-     * @return the Player that is breaking the block
+     * @return The Player that is breaking the block involved in this event
      */
     public Player getPlayer() {
         return player;
@@ -29,9 +35,9 @@ public class BlockBreakEvent extends BlockEvent implements Cancellable {
 
     /**
      * Gets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
-     *
+     *<p />
-     * If a block break event is cancelled, the block will not break.
+     * If a Block Break event is cancelled, the block will not break.
      *
      * @return true if this event is cancelled
      */
@@ -41,9 +47,9 @@ public class BlockBreakEvent extends BlockEvent implements Cancellable {
 
     /**
      * Sets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
-     *
+     *<p />
-     * If a block break event is cancelled, the block will not break.
+     * If a Block Break event is cancelled, the block will not break.
      *
      * @param cancel true if you wish to cancel this event
      */

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

@@ -4,7 +4,9 @@ import org.bukkit.block.Block;
 import org.bukkit.event.Cancellable;
 
 /**
- * Called when a block is destroyed because of being burnt by fire
+ * Called when a block is destroyed as a result of being burnt by fire.
+ *<p />
+ * If a Block Burn event is cancelled, the block will not be destroyed as a result of being burnt by fire.
  */
 public class BlockBurnEvent extends BlockEvent implements Cancellable {
     private boolean cancelled;
@@ -16,9 +18,9 @@ public class BlockBurnEvent extends BlockEvent implements Cancellable {
 
     /**
      * Gets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
-     *
+     *<p />
-     * If a block burn event is cancelled, the block will not be destroyed from being burnt by fire
+     * If a Block Burn event is cancelled, the block will not be destroyed as a result of being burnt by fire.
      *
      * @return true if this event is cancelled
      */
@@ -28,9 +30,9 @@ public class BlockBurnEvent extends BlockEvent implements Cancellable {
 
     /**
      * Sets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
-     *
+     *<p />
-     * If a block burn event is cancelled, the block will not be destroyed from being burnt by fire
+     * If a Block Burn event is cancelled, the block will not be destroyed as a result of being burnt by fire.
      *
      * @param cancel true if you wish to cancel this event
      */

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

@@ -1,13 +1,16 @@
-/**
- *
- */
 package org.bukkit.event.block;
 
 import org.bukkit.block.Block;
 import org.bukkit.Material;
 
 /**
- * @author durron597
+ * Called when we try to place a block, to see if we can build it here or not.
+ *<p />
+ * Note:
+ * <ul>
+ *    <li>The Block returned by getBlock() is the block we are trying to place on, not the block we are trying to place.</li>
+ *    <li>If you want to figure out what is being placed, use {@link #getMaterial()} or {@link #getMaterialId()} instead.</li>
+ * </ul>
  */
 public class BlockCanBuildEvent extends BlockEvent {
     protected boolean buildable;
@@ -20,8 +23,8 @@ public class BlockCanBuildEvent extends BlockEvent {
     }
 
     /**
-     * Returns whether or not the block can be built here. By default, returns
+     * Gets whether or not the block can be built here.
-     * Minecraft's answer on whether the block can be built
+     * By default, returns Minecraft's answer on whether the block can be built here or not.
      *
      * @return boolean whether or not the block can be built
      */
@@ -30,16 +33,28 @@ public class BlockCanBuildEvent extends BlockEvent {
     }
 
     /**
-     * Set whether the block can be built here.
+     * Sets whether the block can be built here or not.
+     *
+     * @param cancel true if you want to allow the block to be built here despite Minecraft's default behaviour
      */
     public void setBuildable(boolean cancel) {
         this.buildable = cancel;
     }
 
+    /**
+     * Gets the Material that we are trying to place.
+     *
+     * @return The Material that we are trying to place
+     */
     public Material getMaterial() {
         return Material.getMaterial(material);
     }
 
+    /**
+     * Gets the Material ID for the Material that we are trying to place.
+     *
+     * @return The Material ID for the Material that we are trying to place
+     */
     public int getMaterialId() {
         return material;
     }

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

@@ -6,7 +6,9 @@ import org.bukkit.event.Cancellable;
 import org.bukkit.inventory.ItemStack;
 
 /**
- * Called when a block is damaged (hit by a player)
+ * Called when a block is damaged by a player.
+ * <p />
+ * If a Block Damage event is cancelled, the block will not be damaged.
  */
 public class BlockDamageEvent extends BlockEvent implements Cancellable {
     private Player player;
@@ -23,36 +25,36 @@ public class BlockDamageEvent extends BlockEvent implements Cancellable {
     }
 
     /**
-     * Returns the player doing the damage
+     * Gets the player damaging the block involved in this event.
      *
-     * @return the player damaging the block
+     * @return The player damaging the block involved in this event
      */
     public Player getPlayer() {
         return player;
     }
 
     /**
-     * Returns if the block is set to instantly break
+     * Gets if the block is set to instantly break when damaged by the player.
      *
-     * @return true If the block should instantly break
+     * @return true if the block should instantly break when damaged by the player
      */
     public boolean getInstaBreak() {
         return instaBreak;
     }
 
     /**
-     * Set if the block should instantly break
+     * Sets if the block should instantly break when damaged by the player.
      *
-     * @param bool If true, the block will instantly break
+     * @param bool true if you want the block to instantly break when damaged by the player
      */
     public void setInstaBreak(boolean bool) {
         this.instaBreak = bool;
     }
 
     /**
-     * Returns the ItemStack in hand
+     * Gets the ItemStack for the item currently in the player's hand.
      *
-     * @return the ItemStack for the item currently in hand
+     * @return The ItemStack for the item currently in the player's hand
      */
     public ItemStack getItemInHand() {
         return itemstack;
@@ -60,9 +62,9 @@ public class BlockDamageEvent extends BlockEvent implements Cancellable {
 
     /**
      * Gets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
-     *
+     *<p />
-     * If a block damage event is cancelled, the block will not be damaged
+     * If a Block Damage event is cancelled, the block will not be damaged.
      *
      * @return true if this event is cancelled
      */
@@ -72,9 +74,9 @@ public class BlockDamageEvent extends BlockEvent implements Cancellable {
 
     /**
      * Sets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
-     *
+     *<p />
-     * If a block damage event is cancelled, the block will not be damaged
+     * If a Block Damage event is cancelled, the block will not be damaged.
      *
      * @param cancel true if you wish to cancel this event
      */

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

@@ -6,7 +6,9 @@ import org.bukkit.inventory.ItemStack;
 import org.bukkit.util.Vector;
 
 /**
- * Event called on dispense of an item from a block.
+ * Called when an item is dispensed from a block.
+ *<p />
+ * If a Block Dispense event is cancelled, the block will not dispense the item.
  */
 public class BlockDispenseEvent extends BlockEvent implements Cancellable {
 
@@ -21,38 +23,39 @@ public class BlockDispenseEvent extends BlockEvent implements Cancellable {
     }
 
     /**
-     * Get the item that is being dispensed. Modifying the returned item
+     * Gets the item that is being dispensed. Modifying the returned item
-     * will have no effect.
+     * will have no effect, you must use {@link #setItem(org.bukkit.inventory.ItemStack)} instead.
      *
-     * @return an ItemStack for the item being dispensed
+     * @return An ItemStack for the item being dispensed
      */
     public ItemStack getItem() {
         return item.clone();
     }
 
     /**
-     * Set the item being dispensed.
+     * Sets the item being dispensed.
      *
-     * @param item
+     * @param item the item being dispensed
      */
     public void setItem(ItemStack item) {
         this.item = item;
     }
 
     /**
-     * Gets the velocity. Modifying the returned Vector will not
+     * Gets the velocity.
-     * change the velocity.
+     *<p />
+     * Note: Modifying the returned Vector will not change the velocity, you must use {@link #setVelocity(org.bukkit.util.Vector)} instead.
      *
-     * @return a Vector for the dispensed item's velocity
+     * @return A Vector for the dispensed item's velocity
      */
     public Vector getVelocity() {
         return velocity.clone();
     }
 
     /**
-     * Set the velocity.
+     * Sets the velocity of the item being dispensed.
      *
-     * @param vel
+     * @param vel the velocity of the item being dispensed
      */
     public void setVelocity(Vector vel) {
         velocity = vel;
@@ -60,7 +63,9 @@ public class BlockDispenseEvent extends BlockEvent implements Cancellable {
 
     /**
      * Gets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
+     *<p />
+     * If a Block Dispense event is cancelled, the block will not dispense the item.
      *
      * @return true if this event is cancelled
      */
@@ -70,7 +75,9 @@ public class BlockDispenseEvent extends BlockEvent implements Cancellable {
 
     /**
      * Sets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
+     *<p />
+     * If a Block Dispense event is cancelled, the block will not dispense the item.
      *
      * @param cancel true if you wish to cancel this event
      */

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

@@ -4,7 +4,7 @@ import org.bukkit.block.Block;
 import org.bukkit.event.Event;
 
 /**
- * Represents a block related event
+ * Represents a block related event.
  */
 public class BlockEvent extends Event {
     protected Block block;
@@ -15,9 +15,9 @@ public class BlockEvent extends Event {
     }
 
     /**
-     * Returns the block involved in this event
+     * Gets the block involved in this event.
      *
-     * @return Block which block is involved in this event
+     * @return The Block which block is involved in this event
      */
     public final Block getBlock() {
         return block;

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

@@ -1,11 +1,18 @@
 package org.bukkit.event.block;
 
-import org.bukkit.Material;
 import org.bukkit.block.Block;
 import org.bukkit.block.BlockState;
 import org.bukkit.event.Cancellable;
 /**
- *Called when a block fades, melts or disappears based on world conditions
+ * Called when a block fades, melts or disappears based on world conditions
+ * <p />
+ * Examples:
+ * <ul>
+ *     <li>Snow melting due to being near a light source.</li>
+ *     <li>Ice melting due to being near a light source.</li>
+ * </ul>
+ * <p />
+ * If a Block Fade event is cancelled, the block will not fade, melt or disappear.
  */
 public class BlockFadeEvent extends BlockEvent implements Cancellable {
     private boolean cancelled;
@@ -18,9 +25,9 @@ public class BlockFadeEvent extends BlockEvent implements Cancellable {
     }
 
     /**
-     * Gets the state of the block that will be fading
+     * Gets the state of the block that will be fading, melting or disappearing.
      *
-     * @return the block state
+     * @return The block state of the block that will be fading, melting or disappearing
      */
     public BlockState getNewState() {
         return newState;
@@ -28,7 +35,9 @@ public class BlockFadeEvent extends BlockEvent implements Cancellable {
 
     /**
      * Gets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
+     *<p />
+     * If a Block Fade event is cancelled, the block will not fade, melt or disappear.
      *
      * @return true if this event is cancelled
      */
@@ -38,7 +47,9 @@ public class BlockFadeEvent extends BlockEvent implements Cancellable {
 
     /**
      * Sets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
+     *<p />
+     * If a Block Fade event is cancelled, the block will not fade, melt or disappear.
      *
      * @param cancel true if you wish to cancel blocks like snow or ice from melting or fading
      */

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

@@ -1,11 +1,21 @@
 package org.bukkit.event.block;
 
-import org.bukkit.Material;
 import org.bukkit.block.Block;
 import org.bukkit.block.BlockState;
 import org.bukkit.event.Cancellable;
+
 /**
- * Called when a block is formed or spreads based on world conditions
+ * Called when a block is formed or spreads based on world conditions.
+ * Use {@link BlockSpreadEvent} to catch blocks that actually spread and don't just "randomly" form.
+ *<p />
+ * Examples:
+ *<ul>
+ *     <li>Snow forming due to a snow storm.</li>
+ *     <li>Ice forming in a snowy Biome like Tiga or Tundra.</li>
+ * </ul>
+ *<p />
+ * If a Block Form event is cancelled, the block will not be formed.
+ * @see BlockSpreadEvent
  */
 public class BlockFormEvent extends BlockEvent implements Cancellable {
     private boolean cancelled;
@@ -26,9 +36,9 @@ public class BlockFormEvent extends BlockEvent implements Cancellable {
     }
 
     /**
-     * Gets the state of the block where it will form or spread to
+     * Gets the state of the block where it will form or spread to.
      *
-     * @return the block state
+     * @return The block state of the block where it will form or spread to
      */
     public BlockState getNewState() {
         return newState;
@@ -36,7 +46,9 @@ public class BlockFormEvent extends BlockEvent implements Cancellable {
 
     /**
      * Gets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
+     *<p />
+     * If a Block Form event is cancelled, the block will not be formed or will not spread.
      *
      * @return true if this event is cancelled
      */
@@ -46,7 +58,9 @@ public class BlockFormEvent extends BlockEvent implements Cancellable {
 
     /**
      * Sets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
+     *<p />
+     * If a Block Form event is cancelled, the block will not be formed or will not spread.
      *
      * @param cancel true if you wish to cancel the block from forming or spreading
      */

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

@@ -5,7 +5,9 @@ import org.bukkit.block.BlockFace;
 import org.bukkit.event.Cancellable;
 
 /**
- * Holds information for events with a source block and a destination block
+ * Represents events with a source block and a destination block, currently only applies to liquid (lava and water).
+ *<p />
+ * If a Block From To event is cancelled, the block will not move (the liquid will not flow).
  */
 public class BlockFromToEvent extends BlockEvent implements Cancellable {
     protected Block to;
@@ -19,18 +21,18 @@ public class BlockFromToEvent extends BlockEvent implements Cancellable {
     }
 
     /**
-     * Gets the location this player moved to
+     * Gets the BlockFace that the block is moving to.
      *
-     * @return Block the block is event originated from
+     * @return The BlockFace that the block is moving to
      */
     public BlockFace getFace() {
         return face;
     }
 
     /**
-     * Convenience method for getting the faced block
+     * Convenience method for getting the faced Block.
      *
-     * @return Block the faced block
+     * @return The faced Block
      */
     public Block getToBlock() {
         if (to == null) {
@@ -41,7 +43,9 @@ public class BlockFromToEvent extends BlockEvent implements Cancellable {
 
      /**
      * Gets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
+     *<p />
+     * If a Block From To event is cancelled, the block will not move.
      *
      * @return true if this event is cancelled
      */
@@ -51,7 +55,9 @@ public class BlockFromToEvent extends BlockEvent implements Cancellable {
 
     /**
      * Sets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
+     *<p />
+     * If a Block From To event is cancelled, the block will not move.
      *
      * @param cancel true if you wish to cancel this event
      */

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

@@ -6,16 +6,15 @@ import org.bukkit.event.Cancellable;
 import org.bukkit.event.Event;
 
 /**
- * Represents a block ignite event.
+ * Called when a block is ignited. If you want to catch when a Player places fire, you need to use {@link BlockPlaceEvent}.
+ *<p />
+ * If a Block Ignite event is cancelled, the block will not be ignited.
  */
 public class BlockIgniteEvent extends BlockEvent implements Cancellable {
     private IgniteCause cause;
     private boolean cancel;
     private Player thePlayer;
 
-    /**
-     * @param Block, IgniteCause, Player or null.
-     */
     public BlockIgniteEvent(Block theBlock, IgniteCause cause, Player thePlayer) {
         super(Event.Type.BLOCK_IGNITE, theBlock);
         this.cause = cause;
@@ -26,9 +25,8 @@ public class BlockIgniteEvent extends BlockEvent implements Cancellable {
     /**
      * Gets the cancellation state of this event. A cancelled event will not
      * be executed in the server, but will still pass to other plugins.
-     *
+     *<p />
-     * If an ignite event is cancelled, the block will not be ignited.
+     * If a Block Ignite event is cancelled, the block will not be ignited.
-     * This will not fire an event.
      *
      * @return true if this event is cancelled
      */
@@ -39,9 +37,8 @@ public class BlockIgniteEvent extends BlockEvent implements Cancellable {
     /**
      * Sets the cancellation state of this event. A cancelled event will not
      * be executed in the server, but will still pass to other plugins.
-     *
+     *<p />
-     * If an ignite event is cancelled, the block will not be ignited.
+     * If a Block Ignite event is cancelled, the block will not be ignited.
-     * This will not fire an event.
      *
      * @param cancel true if you wish to cancel this event
      */
@@ -51,7 +48,8 @@ public class BlockIgniteEvent extends BlockEvent implements Cancellable {
 
     /**
      * Gets the cause of block ignite.
-     * @return An IgniteCause value detailing the cause of block ignition.
+     *
+     * @return An IgniteCause value detailing the cause of block ignition
      */
     public IgniteCause getCause() {
         return cause;
@@ -60,7 +58,7 @@ public class BlockIgniteEvent extends BlockEvent implements Cancellable {
     /**
      * Gets the player who ignited this block
      *
-     * @return Player who placed the block, if not ignited by player returns null.
+     * @return The Player who placed the fire block, if not ignited by a player returns null
      */
     public Player getPlayer() {
         return thePlayer;

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

@@ -14,100 +14,147 @@ public class BlockListener implements Listener {
     public BlockListener() {}
 
     /**
-     * Called when a block is damaged (or broken)
+     * Called when a block is damaged by a player.
+     * <p />
+     * If a Block Damage event is cancelled, the block will not be damaged.
      *
      * @param event Relevant event details
      */
     public void onBlockDamage(BlockDamageEvent event) {}
 
     /**
-     * Called when we try to place a block, to see if we can build it
+     * Called when we try to place a block, to see if we can build it here or not.
+     *<p />
+     * Note:
+     * <ul>
+     *    <li>The Block returned by getBlock() is the block we are trying to place on, not the block we are trying to place.</li>
+     *    <li>If you want to figure out what is being placed, use {@link BlockCanBuildEvent#getMaterial()} or {@link BlockCanBuildEvent#getMaterialId()} instead.</li>
+     * </ul>
+     *
+     * @param event Relevant event details
      */
     public void onBlockCanBuild(BlockCanBuildEvent event) {}
 
     /**
-     * Called when a block flows (water/lava)
+     * Represents events with a source block and a destination block, currently only applies to liquid (lava and water).
+     *<p />
+     * If a Block From To event is cancelled, the block will not move (the liquid will not flow).
      *
      * @param event Relevant event details
      */
     public void onBlockFromTo(BlockFromToEvent event) {}
 
     /**
-     * Called when a block gets ignited
+     * Called when a block is ignited. If you want to catch when a Player places fire, you need to use {@link BlockPlaceEvent}.
+     *<p />
+     * If a Block Ignite event is cancelled, the block will not be ignited.
      *
      * @param event Relevant event details
      */
     public void onBlockIgnite(BlockIgniteEvent event) {}
 
     /**
-     * Called when block physics occurs
+     * Called when block physics occurs.
      *
      * @param event Relevant event details
      */
     public void onBlockPhysics(BlockPhysicsEvent event) {}
 
     /**
-     * Called when a player places a block
+     * Called when a block is placed by a player.
+     *<p />
+     * If a Block Place event is cancelled, the block will not be placed.
      *
      * @param event Relevant event details
      */
     public void onBlockPlace(BlockPlaceEvent event) {}
 
     /**
-     * Called when redstone changes
+     * Called when redstone changes.<br />
-     * From: the source of the redstone change
+     * From: the source of the redstone change.<br />
-     * To: The redstone dust that changed
+     * To: The redstone dust that changed.
      *
      * @param event Relevant event details
      */
     public void onBlockRedstoneChange(BlockRedstoneEvent event) {}
 
     /**
-     * Called when leaves are decaying naturally
+     * Called when leaves are decaying naturally.
+     *<p />
+     * If a Leaves Decay event is cancelled, the leaves will not decay.
      *
      * @param event Relevant event details
      */
     public void onLeavesDecay(LeavesDecayEvent event) {}
 
     /**
-     * Called when a sign is changed
+     * Called when a sign is changed by a player.
+     * <p />
+     * If a Sign Change event is cancelled, the sign will not be changed.
      *
      * @param event Relevant event details
      */
     public void onSignChange(SignChangeEvent event) {}
 
     /**
-     * Called when a block is destroyed from burning
+     * Called when a block is destroyed as a result of being burnt by fire.
+     *<p />
+     * If a Block Burn event is cancelled, the block will not be destroyed as a result of being burnt by fire.
      *
      * @param event Relevant event details
      */
     public void onBlockBurn(BlockBurnEvent event) {}
 
     /**
-     * Called when a block is destroyed by a player.
+     * Called when a block is broken by a player.
+     *<p />
+     * Note:
+     * Plugins wanting to simulate a traditional block drop should set the block to air and utilise their own methods for determining
+     *   what the default drop for the block being broken is and what to do about it, if anything.
+     *<p />
+     * If a Block Break event is cancelled, the block will not break.
      *
      * @param event Relevant event details
      */
     public void onBlockBreak(BlockBreakEvent event) {}
 
     /**
-     * Called when a world is attempting to place a block during a snowfall
+     * Called when a world is attempting to place a block during a snowfall.
      *
      * @param event Relevant event details
-     * @deprecated be prepared to use onBlockForm instead as it will be replacing this event after the RB
+     * @deprecated Be prepared to use onBlockForm instead as it will be replacing this event after the RB
      */
     @Deprecated
     public void onSnowForm(SnowFormEvent event) {}
 
     /**
-     * Called when a block is formed based on world conditions
+     * Called when a block is formed or spreads based on world conditions.
+     * Use {@link BlockSpreadEvent} to catch blocks that actually spread and don't just "randomly" form.
+     *<p />
+     * Examples:
+     *<ul>
+     *     <li>Snow forming due to a snow storm.</li>
+     *     <li>Ice forming in a snowy Biome like Tiga or Tundra.</li>
+     * </ul>
+     *<p />
+     * If a Block Form event is cancelled, the block will not be formed or will not spread.
      *
+     * @see BlockSpreadEvent
      * @param event Relevant event details
      */
     public void onBlockForm(BlockFormEvent event) {}
 
     /**
-     * Called when a block spreads based on world conditions
+     * Called when a block spreads based on world conditions.
+     * Use {@link BlockFormEvent} to catch blocks that "randomly" form instead of actually spread.
+     *<p />
+     * Examples:
+     *<ul>
+     *     <li>Mushrooms spreading.</li>
+     *     <li>Fire spreading.</li>
+     * </ul>
+     *<p />
+     * If a Block Spread event is cancelled, the block will not spread.
      *
      * @param event Relevant event details
      */
@@ -115,13 +162,23 @@ public class BlockListener implements Listener {
 
     /**
      * Called when a block fades, melts or disappears based on world conditions
+     * <p />
+     * Examples:
+     * <ul>
+     *     <li>Snow melting due to being near a light source.</li>
+     *     <li>Ice melting due to being near a light source.</li>
+     * </ul>
+     * <p />
+     * If a Block Fade event is cancelled, the block will not fade, melt or disappear.
      *
      * @param event Relevant event details
      */
     public void onBlockFade(BlockFadeEvent event) {}
 
     /**
-     * Called when a block is dispensing an item
+     * Called when an item is dispensed from a block.
+     *<p />
+     * If a Block Dispense event is cancelled, the block will not dispense the item.
      *
      * @param event Relevant event details
      */

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

@@ -7,7 +7,9 @@ import org.bukkit.event.Cancellable;
 import org.bukkit.inventory.ItemStack;
 
 /**
- * Called when a block is placed by a player
+ * Called when a block is placed by a player.
+ *<p />
+ * If a Block Place event is cancelled, the block will not be placed.
  */
 public class BlockPlaceEvent extends BlockEvent implements Cancellable {
     protected boolean cancel;
@@ -30,6 +32,8 @@ public class BlockPlaceEvent extends BlockEvent implements Cancellable {
     /**
      * Gets the cancellation state of this event. A cancelled event will not
      * be executed in the server, but will still pass to other plugins
+     *<p />
+     * If a Block Place event is cancelled, the block will not be placed.
      *
      * @return true if this event is cancelled
      */
@@ -40,6 +44,8 @@ public class BlockPlaceEvent extends BlockEvent implements Cancellable {
     /**
      * Sets the cancellation state of this event. A cancelled event will not
      * be executed in the server, but will still pass to other plugins
+     *<p />
+     * If a Block Place event is cancelled, the block will not be placed.
      *
      * @param cancel true if you wish to cancel this event
      */
@@ -48,9 +54,9 @@ public class BlockPlaceEvent extends BlockEvent implements Cancellable {
     }
 
     /**
-     * Gets the player who placed this block
+     * Gets the player who placed the block involved in this event.
      *
-     * @return Player who placed the block
+     * @return The Player who placed the block involved in this event
      */
     public Player getPlayer() {
         return player;
@@ -58,25 +64,25 @@ public class BlockPlaceEvent extends BlockEvent implements Cancellable {
 
     /**
      * Clarity method for getting the placed block. Not really needed
-     * except for reasons of clarity
+     * except for reasons of clarity.
      *
-     * @return Block the block that was placed
+     * @return The Block that was placed
      */
     public Block getBlockPlaced() {
         return getBlock();
     }
 
     /**
-     * Returns the state of the block which was replaced. Material type air mostly.
+     * Gets the BlockState for the block which was replaced. Material type air mostly.
      *
-     * @return BlockState of block which was replaced.
+     * @return The BlockState for the block which was replaced.
      */
     public BlockState getBlockReplacedState() {
         return this.replacedBlockState;
     }
 
     /**
-     * Get the block that this block was placed against
+     * Gets the block that this block was placed against
      *
      * @return Block the block that the new block was placed against
      */
@@ -85,9 +91,9 @@ public class BlockPlaceEvent extends BlockEvent implements Cancellable {
     }
 
     /**
-     * Returns the item in your hand when you placed the block
+     * Gets the item in the player's hand when they placed the block.
      *
-     * @return ItemStack the item in your hand when placing the block
+     * @return The ItemStack for the item in the player's hand when they placed the block
      */
     public ItemStack getItemInHand() {
         return itemInHand;

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

@@ -1,10 +1,19 @@
 package org.bukkit.event.block;
 
-import org.bukkit.Material;
 import org.bukkit.block.Block;
 import org.bukkit.block.BlockState;
 /**
- *Represents any event that spreads blocks
+ * Called when a block spreads based on world conditions.
+ * Use {@link BlockFormEvent} to catch blocks that "randomly" form instead of actually spread.
+ *<p />
+ * Examples:
+ *<ul>
+ *     <li>Mushrooms spreading.</li>
+ *     <li>Fire spreading.</li>
+ * </ul>
+ *<p />
+ * If a Block Spread event is cancelled, the block will not spread.
+ * @see BlockFormEvent
  */
 public class BlockSpreadEvent extends BlockFormEvent {
     private Block source;
@@ -15,9 +24,9 @@ public class BlockSpreadEvent extends BlockFormEvent {
     }
 
     /**
-     * Gets the source block
+     * Gets the source block involved in this event.
      *
-     * @return the block state
+     * @return the Block for the source block involved in this event.
      */
     public Block getSource() {
         return source;

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

@@ -4,7 +4,9 @@ import org.bukkit.block.Block;
 import org.bukkit.event.Cancellable;
 
 /**
- * Called on leaves decaying
+ * Called when leaves are decaying naturally.
+ *<p />
+ * If a Leaves Decay event is cancelled, the leaves will not decay.
  */
 public class LeavesDecayEvent extends BlockEvent implements Cancellable {
     private boolean cancel = false;
@@ -16,6 +18,8 @@ public class LeavesDecayEvent extends BlockEvent implements Cancellable {
     /**
      * Gets the cancellation state of this event. A cancelled event will not
      * be executed in the server, but will still pass to other plugins
+     *<p />
+     * If a Leaves Decay event is cancelled, the leaves will not decay.
      *
      * @return true if this event is cancelled
      */
@@ -26,6 +30,8 @@ public class LeavesDecayEvent extends BlockEvent implements Cancellable {
     /**
      * Sets the cancellation state of this event. A cancelled event will not
      * be executed in the server, but will still pass to other plugins
+     *<p />
+     * If a Leaves Decay event is cancelled, the leaves will not decay.
      *
      * @param cancel true if you wish to cancel this event
      */

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

@@ -5,7 +5,9 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
 
 /**
- * Called on sign change
+ * Called when a sign is changed by a player.
+ * <p />
+ * If a Sign Change event is cancelled, the sign will not be changed.
  */
 public class SignChangeEvent extends BlockEvent implements Cancellable {
     private boolean cancel = false;
@@ -19,40 +21,40 @@ public class SignChangeEvent extends BlockEvent implements Cancellable {
     }
 
     /**
-     * Gets the player for this event
+     * Gets the player changing the sign involved in this event.
      *
-     * @return Player player
+     * @return The Player involved in this event.
      */
     public Player getPlayer() {
         return player;
     }
 
     /**
-     * Gets all of the text lines from this event
+     * Gets all of the lines of text from the sign involved in this event.
      *
-     * @return String[] of the event's text lines
+     * @return A String[] of the sign's lines of text
      */
     public String[] getLines() {
         return lines;
     }
 
     /**
-     * Gets a single line from this event
+     * Gets a single line of text from the sign involved in this event.
      *
      * @param index index of the line to get
-     * @return String line
+     * @return The String containing the line of text associated with the provided index
-     * @throws IndexOutOfBoundsException
+     * @throws IndexOutOfBoundsException thrown when the provided index is > 4 and < 0
      */
     public String getLine(int index) throws IndexOutOfBoundsException {
         return lines[index];
     }
 
     /**
-     * Sets a single line for this event
+     * Sets a single line for the sign involved in this event
      *
      * @param index index of the line to set
      * @param line text to set
-     * @throws IndexOutOfBoundsException
+     * @throws IndexOutOfBoundsException thrown when the provided index is > 4 and < 0
      */
     public void setLine(int index, String line) throws IndexOutOfBoundsException {
         lines[index] = line;
@@ -61,6 +63,8 @@ public class SignChangeEvent extends BlockEvent implements Cancellable {
     /**
      * Gets the cancellation state of this event. A cancelled event will not
      * be executed in the server, but will still pass to other plugins
+     * <p />
+     * If a Sign Change event is cancelled, the sign will not be changed.
      *
      * @return true if this event is cancelled
      */
@@ -71,6 +75,8 @@ public class SignChangeEvent extends BlockEvent implements Cancellable {
     /**
      * Sets the cancellation state of this event. A cancelled event will not
      * be executed in the server, but will still pass to other plugins
+     * <p />
+     * If a Sign Change event is cancelled, the sign will not be changed.
      *
      * @param cancel true if you wish to cancel this event
      */

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

@@ -6,7 +6,9 @@ import org.bukkit.Location;
 import org.bukkit.event.Cancellable;
 
 /**
- * Stores data for damage events
+ * Called when a creature is spawned into a world.
+ *<p />
+ * If a Creature Spawn event is cancelled, the creature will not spawn.
  */
 public class CreatureSpawnEvent extends EntityEvent implements Cancellable {
 
@@ -23,18 +25,22 @@ public class CreatureSpawnEvent extends EntityEvent implements Cancellable {
     }
 
     /**
-     * Gets the cancellation state of this event. A canceled event will not
+     * Gets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
+     *<p />
+     * If a Creature Spawn event is cancelled, the creature will not spawn.
      *
-     * @return true if this event is canceled
+     * @return true if this event is cancelled
      */
     public boolean isCancelled() {
         return canceled;
     }
 
     /**
-     * Sets the cancellation state of this event. A canceled event will not
+     * Sets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
+     *<p />
+     * If a Creature Spawn event is cancelled, the creature will not spawn.
      *
      * @param cancel true if you wish to cancel this event
      */
@@ -44,6 +50,7 @@ public class CreatureSpawnEvent extends EntityEvent implements Cancellable {
 
     /**
      * Gets the location at which the creature is spawning.
+     *
      * @return The location at which the creature is spawning
      */
     public Location getLocation() {

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

@@ -4,7 +4,9 @@ import org.bukkit.entity.Entity;
 import org.bukkit.event.Cancellable;
 
 /**
- * Stores data for creepers being (un)powered
+ * Called when a Creeper is struck by lightning.
+ *<p />
+ * If a Creeper Power event is cancelled, the Creeper will not be powered.
  */
 public class CreeperPowerEvent extends EntityEvent implements Cancellable {
 
@@ -28,18 +30,22 @@ public class CreeperPowerEvent extends EntityEvent implements Cancellable {
     }
 
     /**
-     * Gets the cancellation state of this event. A canceled event will not
+     * Gets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
+     *<p />
+     * If a Creeper Power event is cancelled, the Creeper will not be powered.
      *
-     * @return true if this event is canceled
+     * @return true if this event is cancelled
      */
     public boolean isCancelled() {
         return canceled;
     }
 
     /**
-     * Sets the cancellation state of this event. A canceled event will not
+     * Sets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
+     *<p />
+     * If a Creeper Power event is cancelled, the Creeper will not be powered.
      *
      * @param cancel true if you wish to cancel this event
      */
@@ -48,9 +54,9 @@ public class CreeperPowerEvent extends EntityEvent implements Cancellable {
     }
 
     /**
-     * Gets the bolt which is striking the creeper.
+     * Gets the lightning bolt which is striking the Creeper.
      *
-     * @return lightning entity
+     * @return The Entity for the lightning bolt which is striking the Creeper
      */
     public Entity getLightning() {
         return bolt;
@@ -58,6 +64,7 @@ public class CreeperPowerEvent extends EntityEvent implements Cancellable {
 
     /**
      * Gets the cause of the creeper being (un)powered.
+     *
      * @return A PowerCause value detailing the cause of change in power.
      */
     public PowerCause getCause() {

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

@@ -4,7 +4,9 @@ import org.bukkit.entity.Entity;
 import org.bukkit.event.Cancellable;
 
 /**
- * Called when an entity combusts due to the sun
+ * Called when an entity combusts due to the sun.
+ *<p />
+ * If an Entity Combust event is cancelled, the entity will not combust.
  */
 public class EntityCombustEvent extends EntityEvent implements Cancellable {
     private boolean cancel;
@@ -16,7 +18,9 @@ public class EntityCombustEvent extends EntityEvent implements Cancellable {
 
     /**
      * Gets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
+     *<p />
+     * If an Entity Combust event is cancelled, the entity will not combust.
      *
      * @return true if this event is cancelled
      */
@@ -26,7 +30,9 @@ public class EntityCombustEvent extends EntityEvent implements Cancellable {
 
     /**
      * Sets the cancellation state of this event. A cancelled event will not
-     * be executed in the server, but will still pass to other plugins
+     * be executed in the server, but will still pass to other plugins.
+     *<p />
+     * If an Entity Combust event is cancelled, the entity will not combust.
      *
      * @param cancel true if you wish to cancel this event
      */

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

@@ -5,7 +5,7 @@ import org.bukkit.entity.Entity;
 import org.bukkit.event.Cancellable;
 
 /**
- * Stores details for damage events where the damager is a block
+ * Called when an entity is damaged by a block
  */
 public class EntityDamageByBlockEvent extends EntityDamageEvent implements Cancellable {
 
@@ -18,6 +18,7 @@ public class EntityDamageByBlockEvent extends EntityDamageEvent implements Cance
 
     /**
      * Returns the block that damaged the player.
+     *
      * @return Block that damaged the player
      */
     public Block getDamager() {

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

@@ -4,7 +4,7 @@ import org.bukkit.entity.Entity;
 import org.bukkit.event.Cancellable;
 
 /**
- * Stores details for damage events where the damager is a block
+ * Called when an entity is damaged by an entity
  */
 public class EntityDamageByEntityEvent extends EntityDamageEvent implements Cancellable {
 
@@ -17,6 +17,7 @@ public class EntityDamageByEntityEvent extends EntityDamageEvent implements Canc
 
     /**
      * Returns the entity that damaged the defender.
+     *
      * @return Entity that damaged the defender.
      */
     public Entity getDamager() {

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

@@ -16,6 +16,7 @@ public class EntityEvent extends Event {
 
     /**
      * Returns the Entity involved in this event
+     *
      * @return Entity who is involved in this event
      */
     public final Entity getEntity() {

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

@@ -6,7 +6,6 @@ import org.bukkit.event.Cancellable;
 
 /**
  * Called when an entity interacts with an object
- *
  */
 public class EntityInteractEvent extends EntityEvent implements Cancellable {
     protected Block block;
@@ -22,7 +21,7 @@ public class EntityInteractEvent extends EntityEvent implements Cancellable {
      * Gets the cancellation state of this event. Set to true if you
      * want to prevent buckets from placing water and so forth
      *
-     * @return boolean cancellation state
+     * @return true if this event is cancelled
      */
     public boolean isCancelled() {
         return cancelled;
@@ -32,10 +31,6 @@ public class EntityInteractEvent extends EntityEvent implements Cancellable {
      * Sets the cancellation state of this event. A canceled event will not
      * be executed in the server, but will still pass to other plugins
      *
-     * Canceling this event will prevent use of food (player won't lose the
-     * food item), prevent bows/snowballs/eggs from firing, etc. (player won't
-     * lose the ammo)
-     *
      * @param cancel true if you wish to cancel this event
      */
     public void setCancelled(boolean cancel) {
@@ -45,7 +40,7 @@ public class EntityInteractEvent extends EntityEvent implements Cancellable {
     /**
      * Returns the involved block
      *
-     * @return Block returns the block clicked with this item.
+     * @return the block clicked with this item.
      */
     public Block getBlock() {
         return block;

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

@@ -11,7 +11,9 @@ public class EntityListener implements Listener {
     public EntityListener() {}
 
     /**
-     * Called when a creature is spawned into a world
+     * Called when a creature is spawned into a world.
+     *<p />
+     * If a Creature Spawn event is cancelled, the creature will not spawn.
      *
      * @param event Relevant event details
      */
@@ -25,7 +27,9 @@ public class EntityListener implements Listener {
     public void onItemSpawn(ItemSpawnEvent event) {}
 
     /**
-     * Called when an entity combusts due to the sun
+     * Called when an entity combusts due to the sun.
+     *<p />
+     * If an Entity Combust event is cancelled, the entity will not combust.
      *
      * @param event Relevant event details
      */
@@ -102,7 +106,9 @@ public class EntityListener implements Listener {
     public void onPigZap(PigZapEvent event) {}
 
     /**
-     * Called when a Creeper is struck by lightning
+     * Called when a Creeper is struck by lightning.
+     *<p />
+     * If a Creeper Power event is cancelled, the Creeper will not be powered.
      *
      * @param event Relevant event details
      */

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

@@ -21,6 +21,7 @@ public class EntityRegainHealthEvent extends EntityEvent implements Cancellable
 
     /**
      * Gets the amount of regained health
+     *
      * @return The amount of health regained
      */
     public int getAmount() {
@@ -41,7 +42,6 @@ public class EntityRegainHealthEvent extends EntityEvent implements Cancellable
      * be executed in the server, but will still pass to other plugins
      *
      * If a health-regain event is cancelled, the entity won't get health.
-     * This will not fire an event.
      *
      * @return true if this event is cancelled
      */
@@ -54,7 +54,6 @@ public class EntityRegainHealthEvent extends EntityEvent implements Cancellable
      * be executed in the server, but will still pass to other plugins
      *
      * If a health-regain event is cancelled, the entity won't get health.
-     * This will not fire an event.
      *
      * @param cancel true if you wish to cancel this event
      */
@@ -72,7 +71,7 @@ public class EntityRegainHealthEvent extends EntityEvent implements Cancellable
     }
 
     /**
-     * An enum to specify the type of health regaining
+     * An enum to specify the type of health regaining that is occurring
      */
     public enum RegainReason {
 

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

@@ -39,6 +39,7 @@ public class ItemSpawnEvent extends EntityEvent implements Cancellable {
 
     /**
      * Gets the location at which the item is spawning.
+     *
      * @return The location at which the item is spawning
      */
     public Location getLocation() {

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

@@ -6,7 +6,6 @@ import org.bukkit.event.Cancellable;
 
 /**
  * This event is fired when the player is almost about to enter the bed.
- * It can be cancelled.
  */
 public class PlayerBedEnterEvent extends PlayerEvent implements Cancellable {
 

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

@@ -7,6 +7,9 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
 import org.bukkit.inventory.ItemStack;
 
+/**
+ * Called when a player empties a bucket
+ */
 public class PlayerBucketEmptyEvent extends PlayerEvent implements Cancellable {
     ItemStack itemStack;
     boolean cancelled = false;

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

@@ -7,6 +7,9 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
 import org.bukkit.inventory.ItemStack;
 
+/**
+ * Called when a player fills a bucket
+ */
 public class PlayerBucketFillEvent extends PlayerEvent implements Cancellable {
     ItemStack itemStack;
     boolean cancelled = false;