Updated Event list

1 files changed, 269 insertions, 44 deletions

diff --git a/src/main/java/org/bukkit/event/Event.java b/src/main/java/org/bukkit/event/Event.java
index fe8a6d31..b0e4e325 100644
--- a/src/main/java/org/bukkit/event/Event.java
+++ b/src/main/java/org/bukkit/event/Event.java
@@ -1,6 +1,8 @@
 
 package org.bukkit.event;
 
+import com.sun.org.apache.bcel.internal.generic.AALOAD;
+
 /**
  * Represents an event
  */
@@ -34,8 +36,9 @@ public abstract class Event {
     }
     
     /**
-     * Gets the event's name. Should only be used if getType returns null.
-     * @return 
+     * Gets the event's name. Should only be used if getType() == Type.CUSTOM
+     *
+     * @return Name of this event
      */
     public final String getEventName() {
         if(type!=Type.CUSTOM_EVENT) return type.toString();
@@ -43,7 +46,7 @@ public abstract class Event {
     }
 
     /**
-     * Represents an events priority
+     * Represents an events priority in execution
      */
     public enum Priority {
         /**
@@ -81,85 +84,302 @@ public abstract class Event {
         Monitor
     }
 
+    /**
+     * Represents a category used by Type
+     */
     public enum Category {
+        /**
+         * Represents Player-based events
+         * @see Category.LIVING_ENTITY
+         */
         PLAYER,
+
+        /**
+         * Represents Block-based events
+         */
         BLOCK,
-        ITEM,
-        ENVIRONMENT,
-        ENTITY,
+
+        /**
+         * Represents LivingEntity-based events
+         */
+        LIVING_ENTITY,
+
+        /**
+         * Represents Vehicle-based events
+         */
         VEHICLE,
+
+        /**
+         * Represents World-based events
+         */
+        WORLD,
+
+        /**
+         * Represents Server and Plugin based events
+         */
+        SERVER,
+
+        /**
+         * Represents Inventory-based events
+         */
         INVENTORY,
-        SIGN,
-        CUSTOM;
+
+        /**
+         * Any miscellaneous events
+         */
+        MISCELLANEOUS;
     }
 
+    /**
+     * Provides a lookup for all core events
+     */
     public enum Type {
+        /**
+         * PLAYER EVENTS
+         */
+
         /** 
-         * Player Events
+         * Called when a player joins a server
          */
         PLAYER_JOIN (Category.PLAYER),
+
+        /**
+         * Called when a player is attempting to join a server
+         */
         PLAYER_LOGIN (Category.PLAYER),
+
+        /**
+         * Called when a player sends a chat message
+         */
         PLAYER_CHAT (Category.PLAYER),
+
+        /**
+         * Called when a player attempts to use a command
+         */
         PLAYER_COMMAND (Category.PLAYER),
+
+        /**
+         * Called when a player leaves a server
+         */
         PLAYER_QUIT (Category.PLAYER),
+
+        /**
+         * Called when a player moves position in the world
+         */
         PLAYER_MOVE (Category.PLAYER),
-        //PLAYER_ANIMATION (Category.PLAYER),
+
+        /**
+         * Called when a player undergoes an animation, such as arm swinging
+         */
+        PLAYER_ANIMATION (Category.PLAYER),
+
+        /**
+         * Called when a player teleports from one position to another
+         */
         PLAYER_TELEPORT (Category.PLAYER),
+
+        /**
+         * BLOCK EVENTS
+         */
+
         /** 
-         * Block Events
+         * Called when a block is damaged (hit by a player)
+         */
+        BLOCK_DAMAGED (Category.BLOCK),
+
+        /**
+         * Called when a block is undergoing a check on whether it can be built
+         *
+         * For example, cacti cannot be built on grass unless overridden here
          */
-        BLOCK_BROKEN (Category.BLOCK),
         BLOCK_CANBUILD (Category.BLOCK),
+
+        /**
+         * Called when a block of water or lava attempts to flow into another
+         * block
+         */
         BLOCK_FLOW (Category.BLOCK),
+
+        /**
+         * Called when a block is being set on fire from another block, such as
+         * an adjacent block of fire attempting to set fire to wood
+         */
         BLOCK_IGNITE (Category.BLOCK),
+
+        /**
+         * Called when a block undergoes a physics check
+         *
+         * A physics check is commonly called when an adjacent block changes
+         * type
+         */
         BLOCK_PHYSICS (Category.BLOCK),
+
+        /**
+         * Called when a player is attempting to place a block
+         */
         BLOCK_PLACED (Category.BLOCK),
-        BLOCK_RIGHTCLICKED (Category.BLOCK),
+
+        /**
+         * Called when a specific block is being sent to a player
+         */
+        BLOCK_SENT (Category.BLOCK),
+
+        /**
+         * Called when a liquid attempts to flow into a block which already
+         * contains a "breakable" block, such as redstone wire
+         */
+        LIQUID_DESTROY (Category.BLOCK),
+
+        /**
+         * Called when a block changes redstone current. Only triggered on blocks
+         * that are actually capable of transmitting or carrying a redstone
+         * current
+         */
         REDSTONE_CHANGE (Category.BLOCK),
 
+        /**
+         * INVENTORY EVENTS
+         */
 
         /** 
-         * Item Events
+         * Called when a player opens an inventory
+         */
+        INVENTORY_OPEN (Category.INVENTORY),
 
-        ITEM_DROP (Category.ITEM),
-        ITEM_PICK_UP (Category.ITEM),
-        ITEM_USE (Category.ITEM),
-        /** 
-         * Environment Events
+        /**
+         * Called when a player closes an inventory
+         */
+        INVENTORY_CLOSE (Category.INVENTORY),
+
+        /**
+         * Called when a player clicks on an inventory slot
+         */
+        INVENTORY_CLICK (Category.INVENTORY),
+
+        /**
+         * Called when an inventory slot changes values or type
+         */
+        INVENTORY_CHANGE (Category.INVENTORY),
+
+        /**
+         * Called when a player is attempting to perform an inventory transaction
+         */
+        INVENTORY_TRANSACTION (Category.INVENTORY),
+
+        /**
+         * SERVER EVENTS
+         */
+
+        /**
+         * Called when a plugin is enabled
+         */
+        PLUGIN_ENABLE (Category.SERVER),
+
+        /**
+         * Called when a plugin is disabled
+         */
+        PLUGIN_DISABLE (Category.SERVER),
+
+        /**
+         * WORLD EVENTS
+         */
+
+        /**
+         * Called when a chunk is loaded
+         *
+         * If a new chunk is being generated for loading, it will call
+         * Type.CHUNK_GENERATION and then Type.CHUNK_LOADED upon completion
+         */
+        CHUNK_LOADED (Category.WORLD),
+
+        /**
+         * Called when a chunk is unloaded
+         */
+        CHUNK_UNLOADED (Category.WORLD),
+
+        /**
+         * Called when a chunk needs to be generated
+         */
+        CHUNK_GENERATION (Category.WORLD),
+
+        /**
+         * Called when an ItemEntity spawns in the world
+         */
+        ITEM_SPAWN (Category.WORLD),
+
+        /**
+         * LIVING_ENTITY EVENTS
+         */
 
-        IGNITE (Category.ENVIRONMENT),
-        FLOW (Category.ENVIRONMENT),
-        EXPLODE (Category.ENVIRONMENT),
-        LIQUID_DESTROY (Category.ENVIRONMENT),
         /** 
-         * Non-player Entity Events
+         * Called when a creature, either hostile or neutral, attempts to spawn
+         * in the world "naturally"
+         */
+        CREATURE_SPAWN (Category.LIVING_ENTITY),
+
+        /**
+         * Called when a LivingEntity is damaged by the environment (for example,
+         * falling or lava)
+         */
+        ENTITY_DAMAGED_ENVIRONMENT (Category.LIVING_ENTITY),
+
+        /**
+         * Called when a LivingEntity is damaged by another LivingEntity
+         */
+        ENTITY_DAMAGED (Category.LIVING_ENTITY),
+
+        /**
+         * Called when a LivingEntity dies
+         */
+        ENTITY_DEATH (Category.LIVING_ENTITY),
+
+        /**
+         * VEHICLE EVENTS
+         */
 
-        MOB_SPAWN (Category.ENTITY),
-        DAMAGE (Category.ENTITY),
-        HEALTH_CHANGE (Category.ENTITY),
-        ATTACK (Category.ENTITY), // Need to look into this category more
         /** 
-         * Vehicle Events
+         * Called when a vehicle is placed by a player
+         */
+        VEHICLE_PLACED (Category.VEHICLE),
+
+        /**
+         * Called when a vehicle is damaged by a LivingEntity
+         */
+        VEHICLE_DAMAGED (Category.VEHICLE),
+
+        /**
+         * Called when a vehicle collides with an Entity
+         */
+        VEHICLE_COLLISION_ENTITY (Category.VEHICLE),
 
-        VEHICLE_CREATE (Category.VEHICLE),
-        VEHICLE_UPDATE (Category.VEHICLE),
-        VEHICLE_DAMAGE (Category.VEHICLE),
-        VEHICLE_COLLISION (Category.VEHICLE),
-        VEHICLE_DESTROYED (Category.VEHICLE),
+        /**
+         * Called when a vehicle collides with a Block
+         */
+        VEHICLE_COLLISION_BLOCK (Category.VEHICLE),
+
+        /**
+         * Called when a vehicle is entered by a LivingEntity
+         */
         VEHICLE_ENTERED (Category.VEHICLE),
-        VEHICLE_POSITIONCHANGE (Category.VEHICLE),
-        /** 
-         * Inventory Events
 
-        OPEN_INVENTORY (Category.INVENTORY),
-        /** 
-         * Sign Events (Item events??)
+        /**
+         * Called when a vehicle is exited by a LivingEntity
+         */
+        VEHICLE_EXITED (Category.VEHICLE),
+
+        /**
+         * Called when a vehicle moves position in the world
+         */
+        VEHICLE_MOVE (Category.VEHICLE),
 
-        SIGN_SHOW (Category.SIGN),
-        SIGN_CHANGE (Category.SIGN)
+        /**
+         * MISCELLANEOUS EVENTS
          */
-        
-        CUSTOM_EVENT (Category.CUSTOM);
+
+        /**
+         * Represents a custom event, isn't actually used
+         */
+        CUSTOM_EVENT (Category.MISCELLANEOUS);
 
         private final Category category;
         
@@ -167,6 +387,11 @@ public abstract class Event {
             this.category = category;
         }
 
+        /**
+         * Gets the Category assigned to this event
+         *
+         * @return Category of this Event.Type
+         */
         public Category getCategory() {
             return category;
         }