JavaDoc cleanup.

12 files changed, 85 insertions, 36 deletions

diff --git a/src/main/java/org/bukkit/event/block/BlockBreakEvent.java b/src/main/java/org/bukkit/event/block/BlockBreakEvent.java
index 375a0756..9b3bf2d3 100644
--- a/src/main/java/org/bukkit/event/block/BlockBreakEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockBreakEvent.java
@@ -5,8 +5,7 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
 
 /**
- *
- * @author Meaglin
+ * Called when a block is broken by a player
  */
 public class BlockBreakEvent extends BlockEvent implements Cancellable {
 
@@ -22,16 +21,32 @@ public class BlockBreakEvent extends BlockEvent implements Cancellable {
     /**
      * Returns the player doing the damage
      *
-     * @return
+     * @return the Player doing the damage
      */
     public Player getPlayer() {
         return player;
     }
 
+    /**
+     * Gets the cancellation state of this event. A cancelled event will not
+     * be executed in the server, but will still pass to other plugins
+     *
+     * If a block break event is cancelled, the block will not break.
+     *
+     * @return true if this event is cancelled
+     */
     public boolean isCancelled() {
         return cancel;
     }
 
+    /**
+     * Sets the cancellation state of this event. A cancelled event will not
+     * be executed in the server, but will still pass to other plugins
+     *
+     * If a block break event is cancelled, the block will not break.
+     *
+     * @param cancel true if you wish to cancel this event
+     */
     public void setCancelled(boolean cancel) {
         this.cancel = cancel;
     }
diff --git a/src/main/java/org/bukkit/event/block/BlockBurnEvent.java b/src/main/java/org/bukkit/event/block/BlockBurnEvent.java
index 23e37f23..453d67a9 100644
--- a/src/main/java/org/bukkit/event/block/BlockBurnEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockBurnEvent.java
@@ -5,7 +5,6 @@ import org.bukkit.event.Cancellable;
 
 /**
  * Called when a block is destroyed because of being burnt by fire
- * @author tkelly
  */
 public class BlockBurnEvent extends BlockEvent implements Cancellable {
     private boolean cancelled;
@@ -15,13 +14,25 @@ public class BlockBurnEvent extends BlockEvent implements Cancellable {
         this.cancelled = false;
     }
 
+    /**
+     * Gets the cancellation state of this event. A cancelled event will not
+     * be executed in the server, but will still pass to other plugins
+     *
+     * If a block burn event is cancelled, the block will not be destroyed from being burnt by fire
+     *
+     * @return true if this event is cancelled
+     */
     public boolean isCancelled() {
         return cancelled;
     }
 
     /**
-     * Allow for the block to be stopped from being destroyed
-     * @param cancel
+     * Sets the cancellation state of this event. A cancelled event will not
+     * be executed in the server, but will still pass to other plugins
+     *
+     * If a block burn event is cancelled, the block will not be destroyed from being burnt by fire
+     *
+     * @param cancel true if you wish to cancel this event
      */
     public void setCancelled(boolean cancel) {
         this.cancelled = cancel;
diff --git a/src/main/java/org/bukkit/event/block/BlockDamageEvent.java b/src/main/java/org/bukkit/event/block/BlockDamageEvent.java
index 1cd489fa..e9981a37 100644
--- a/src/main/java/org/bukkit/event/block/BlockDamageEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockDamageEvent.java
@@ -6,7 +6,7 @@ import org.bukkit.event.Cancellable;
 import org.bukkit.inventory.ItemStack;
 
 /**
- * @author tkelly
+ * Called when a block is damaged by a player
  */
 public class BlockDamageEvent extends BlockEvent implements Cancellable {
     private Player player;
@@ -25,7 +25,7 @@ public class BlockDamageEvent extends BlockEvent implements Cancellable {
     /**
      * Returns the player doing the damage
      *
-     * @return
+     * @return the player damaging the block
      */
     public Player getPlayer() {
         return player;
@@ -34,7 +34,7 @@ public class BlockDamageEvent extends BlockEvent implements Cancellable {
     /**
      * Returns if the block is set to instantly break
      *
-     * @return boolean If the block should instantly break
+     * @return true If the block should instantly break
      */
     public boolean getInstaBreak() {
         return instaBreak;
@@ -42,6 +42,8 @@ public class BlockDamageEvent extends BlockEvent implements Cancellable {
 
     /**
      * Set if the block should instantly break
+     *
+     * @param bool If true, the block will instantly break
      */
     public void setInstaBreak(boolean bool) {
         this.instaBreak = bool;
@@ -50,16 +52,32 @@ public class BlockDamageEvent extends BlockEvent implements Cancellable {
     /**
      * Returns the ItemStack in hand
      *
-     * @return Currently wielding itemstack
+     * @return the ItemStack for the item currently in hand
      */
     public ItemStack getItemInHand() {
         return itemstack;
     }
 
+    /**
+     * Gets the cancellation state of this event. A cancelled event will not
+     * be executed in the server, but will still pass to other plugins
+     *
+     * If a block damage event is cancelled, the block will not be damaged
+     *
+     * @return true if this event is cancelled
+     */
     public boolean isCancelled() {
         return cancel;
     }
 
+    /**
+     * Sets the cancellation state of this event. A cancelled event will not
+     * be executed in the server, but will still pass to other plugins
+     *
+     * If a block damage event is cancelled, the block will not be damaged
+     *
+     * @param cancel true if you wish to cancel this event
+     */
     public void setCancelled(boolean cancel) {
         this.cancel = cancel;
     }
diff --git a/src/main/java/org/bukkit/event/block/BlockDispenseEvent.java b/src/main/java/org/bukkit/event/block/BlockDispenseEvent.java
index 55845a6f..0ca39ab6 100644
--- a/src/main/java/org/bukkit/event/block/BlockDispenseEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockDispenseEvent.java
@@ -7,8 +7,6 @@ import org.bukkit.util.Vector;
 
 /**
  * Event called on dispense of an item from a block.
- *
- * @author sk89q
  */
 public class BlockDispenseEvent extends BlockEvent implements Cancellable {
 
@@ -26,7 +24,7 @@ public class BlockDispenseEvent extends BlockEvent implements Cancellable {
      * Get the item that is being dispensed. Modifying the returned item
      * will have no effect.
      *
-     * @return
+     * @return an ItemStack for the item being dispensed
      */
     public ItemStack getItem() {
         return item.clone();
@@ -45,7 +43,7 @@ public class BlockDispenseEvent extends BlockEvent implements Cancellable {
      * Gets the velocity. Modifying the returned Vector will not
      * change the velocity.
      *
-     * @return
+     * @return a Vector for the dispensed item's velocity
      */
     public Vector getVelocity() {
         return velocity.clone();
diff --git a/src/main/java/org/bukkit/event/block/BlockEvent.java b/src/main/java/org/bukkit/event/block/BlockEvent.java
index d7875348..2afb2ca5 100644
--- a/src/main/java/org/bukkit/event/block/BlockEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockEvent.java
@@ -16,6 +16,7 @@ public class BlockEvent extends Event {
 
     /**
      * Returns the block involved in this event
+     *
      * @return Block which block is involved in this event
      */
     public final Block getBlock() {
diff --git a/src/main/java/org/bukkit/event/block/BlockFadeEvent.java b/src/main/java/org/bukkit/event/block/BlockFadeEvent.java
index 9dd9c96c..c6f78556 100644
--- a/src/main/java/org/bukkit/event/block/BlockFadeEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockFadeEvent.java
@@ -40,7 +40,7 @@ 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
      *
-     * @param cancel true if you wish to cancel snow from forming during a ice formation
+     * @param cancel true if you wish to cancel blocks like snow or ice from melting or fading
      */
     public void setCancelled(boolean cancel) {
         this.cancelled = cancel;
diff --git a/src/main/java/org/bukkit/event/block/BlockFormEvent.java b/src/main/java/org/bukkit/event/block/BlockFormEvent.java
index a769fd40..578fde19 100644
--- a/src/main/java/org/bukkit/event/block/BlockFormEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockFormEvent.java
@@ -48,7 +48,7 @@ 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
      *
-     * @param cancel true if you wish to cancel snow from forming during a ice formation
+     * @param cancel true if you wish to cancel the block from forming or spreading
      */
     public void setCancelled(boolean cancel) {
         this.cancelled = cancel;
diff --git a/src/main/java/org/bukkit/event/block/BlockFromToEvent.java b/src/main/java/org/bukkit/event/block/BlockFromToEvent.java
index 6aaa8448..e053c96d 100644
--- a/src/main/java/org/bukkit/event/block/BlockFromToEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockFromToEvent.java
@@ -39,10 +39,22 @@ public class BlockFromToEvent extends BlockEvent implements Cancellable {
         return to;
     }
 
+     /**
+     * Gets the cancellation state of this event. A cancelled event will not
+     * be executed in the server, but will still pass to other plugins
+     *
+     * @return true if this event is cancelled
+     */
     public boolean isCancelled() {
         return cancel;
     }
 
+    /**
+     * Sets the cancellation state of this event. A cancelled event will not
+     * be executed in the server, but will still pass to other plugins
+     *
+     * @param cancel true if you wish to cancel this event
+     */
     public void setCancelled(boolean cancel) {
         this.cancel = cancel;
     }
diff --git a/src/main/java/org/bukkit/event/block/BlockIgniteEvent.java b/src/main/java/org/bukkit/event/block/BlockIgniteEvent.java
index c0f6210e..05af0fc2 100644
--- a/src/main/java/org/bukkit/event/block/BlockIgniteEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockIgniteEvent.java
@@ -6,8 +6,6 @@ import org.bukkit.event.Cancellable;
 import org.bukkit.event.Event;
 
 /**
- * @author SpeaKeasY
- *
  * Represents a block ignite event.
  */
 public class BlockIgniteEvent extends BlockEvent implements Cancellable {
@@ -78,7 +76,7 @@ public class BlockIgniteEvent extends BlockEvent implements Cancellable {
          */
         LAVA,
         /**
-         * Block ignition caused by player using flint-and-steel.
+         * Block ignition caused by a player using flint-and-steel.
          */
         FLINT_AND_STEEL,
         /**
@@ -86,7 +84,7 @@ public class BlockIgniteEvent extends BlockEvent implements Cancellable {
          */
         SPREAD,
         /**
-         * That thing form the sky.
+         * Block ignition caused by lightning.
          */
         LIGHTNING,
     }
diff --git a/src/main/java/org/bukkit/event/block/BlockListener.java b/src/main/java/org/bukkit/event/block/BlockListener.java
index b3623459..8bf86383 100644
--- a/src/main/java/org/bukkit/event/block/BlockListener.java
+++ b/src/main/java/org/bukkit/event/block/BlockListener.java
@@ -5,8 +5,6 @@ import org.bukkit.plugin.AuthorNagException;
 
 /**
  * Handles all events thrown in relation to Blocks
- *
- * @author durron597
  */
 public class BlockListener implements Listener {
 
@@ -31,15 +29,8 @@ public class BlockListener implements Listener {
      * Called when a block flows (water/lava)
      *
      * @param event Relevant event details
-     * @throws BukkitAuthorNagException
      */
-    public void onBlockFromTo(BlockFromToEvent event) {
-        onBlockFlow(event);
-        throw new AuthorNagException("onBlockFlow has been deprecated, use onBlockFromTo");
-    }
-
-    // Prevent compilation of old signatures TODO: Remove after 1.4
-    @Deprecated public void onBlockFlow(BlockFromToEvent event) {}
+    public void onBlockFromTo(BlockFromToEvent event) {}
 
     /**
      * Called when a block gets ignited
diff --git a/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java b/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java
index b6eae10b..a400aa6e 100644
--- a/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java
@@ -7,7 +7,7 @@ import org.bukkit.event.Cancellable;
 import org.bukkit.inventory.ItemStack;
 
 /**
- * Not implemented yet
+ * Called when a block is placed by a player
  */
 public class BlockPlaceEvent extends BlockEvent implements Cancellable {
     protected boolean cancel;
@@ -109,6 +109,8 @@ public class BlockPlaceEvent extends BlockEvent implements Cancellable {
     /**
      * Sets the canBuild state of this event. Set to true if you want the
      * player to be able to build.
+     *
+     * @param canBuild true if you want the player to be able to build
      */
     public void setBuild(boolean canBuild) {
         this.canBuild = canBuild;
diff --git a/src/main/java/org/bukkit/event/entity/EntityDamageEvent.java b/src/main/java/org/bukkit/event/entity/EntityDamageEvent.java
index 28d6257b..238ba61c 100644
--- a/src/main/java/org/bukkit/event/entity/EntityDamageEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityDamageEvent.java
@@ -53,6 +53,7 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
 
     /**
      * Gets the amount of damage caused by the Block
+     *
      * @return The amount of damage caused by the Block
      */
     public int getDamage() {
@@ -61,7 +62,8 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
 
     /**
      * Sets the amount of damage caused by the Block
-     * @return The amount of damage caused by the Block
+     *
+     * @param damage The amount of damage caused by the Block
      */
     public void setDamage(int damage) {
         this.damage = damage;
@@ -69,6 +71,7 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
 
     /**
      * Gets the cause of the damage.
+     *
      * @return A DamageCause value detailing the cause of the damage.
      */
     public DamageCause getCause() {
@@ -93,15 +96,15 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
          */
         ENTITY_ATTACK,
         /**
-         * Damage caused when an entity falls a distance greater than 3 blocks
+         * Damage caused by being put in a block
          *
-         * Damage: fall height - 3.0
+         * Damage: 1
          */
         SUFFOCATION,
         /**
-         * Damage caused by being put in a block
+         * Damage caused when an entity falls a distance greater than 3 blocks
          *
-         * Damage: 1
+         * Damage: fall height - 3.0
          */
         FALL,
         /**