(Relatively) minor javadoc cleanup

4 files changed, 275 insertions, 111 deletions

diff --git a/src/main/java/org/bukkit/ChatColor.java b/src/main/java/org/bukkit/ChatColor.java
index e0dbcc47..2ce5e82f 100644
--- a/src/main/java/org/bukkit/ChatColor.java
+++ b/src/main/java/org/bukkit/ChatColor.java
@@ -7,21 +7,69 @@ import java.util.Map;
  * All supported color values for chat
  */
 public enum ChatColor {
+    /**
+     * Represents black
+     */
     BLACK(0x0),
+    /**
+     * Represents dark blue
+     */
     DARK_BLUE(0x1),
+    /**
+     * Represents dark green
+     */
     DARK_GREEN(0x2),
+    /**
+     * Represents dark blue (aqua)
+     */
     DARK_AQUA(0x3),
+    /**
+     * Represents dark red
+     */
     DARK_RED(0x4),
+    /**
+     * Represents dark purple
+     */
     DARK_PURPLE(0x5),
+    /**
+     * Represents gold
+     */
     GOLD(0x6),
+    /**
+     * Represents gray
+     */
     GRAY(0x7),
+    /**
+     * Represents dark gray
+     */
     DARK_GRAY(0x8),
+    /**
+     * Represents blue
+     */
     BLUE(0x9),
+    /**
+     * Represents green
+     */
     GREEN(0xA),
+    /**
+     * Represents aqua
+     */
     AQUA(0xB),
+    /**
+     * Represents red
+     */
     RED(0xC),
+    /**
+     * Represents light purple
+     */
     LIGHT_PURPLE(0xD),
+    /**
+     * Represents yellow
+     */
     YELLOW(0xE),
+    /**
+     * Represents white
+     */
     WHITE(0xF);
 
     private final int code;
@@ -31,6 +79,11 @@ public enum ChatColor {
         this.code = code;
     }
 
+    /**
+     * Gets the data value associated with this color
+     *
+     * @return An integer value of this color code
+     */
     public int getCode() {
         return code;
     }
@@ -40,6 +93,12 @@ public enum ChatColor {
         return String.format("\u00A7%x", code);
     }
 
+    /**
+     * Gets the color represented by the specified color code
+     *
+     * @param code Code to check
+     * @return Associative {@link Color} with the given code, or null if it doesn't exist
+     */
     public static ChatColor getByCode(final int code) {
         return colors.get(code);
     }
diff --git a/src/main/java/org/bukkit/DyeColor.java b/src/main/java/org/bukkit/DyeColor.java
index 1bf19fb8..594d23dc 100644
--- a/src/main/java/org/bukkit/DyeColor.java
+++ b/src/main/java/org/bukkit/DyeColor.java
@@ -8,21 +8,69 @@ import java.util.Map;
  * All supported color values for dyes and cloth
  */
 public enum DyeColor {
+    /**
+     * Represents white dye
+     */
     WHITE((byte) 0x0),
+    /**
+     * Represents orange dye
+     */
     ORANGE((byte) 0x1),
+    /**
+     * Represents magenta dye
+     */
     MAGENTA((byte) 0x2),
+    /**
+     * Represents light blue dye
+     */
     LIGHT_BLUE((byte) 0x3),
+    /**
+     * Represents yellow dye
+     */
     YELLOW((byte) 0x4),
+    /**
+     * Represents lime dye
+     */
     LIME((byte) 0x5),
+    /**
+     * Represents pink dye
+     */
     PINK((byte) 0x6),
+    /**
+     * Represents gray dye
+     */
     GRAY((byte) 0x7),
+    /**
+     * Represents silver dye
+     */
     SILVER((byte) 0x8),
+    /**
+     * Represents cyan dye
+     */
     CYAN((byte) 0x9),
+    /**
+     * Represents purple dye
+     */
     PURPLE((byte) 0xA),
+    /**
+     * Represents blue dye
+     */
     BLUE((byte) 0xB),
+    /**
+     * Represents brown dye
+     */
     BROWN((byte) 0xC),
+    /**
+     * Represents green dye
+     */
     GREEN((byte) 0xD),
+    /**
+     * Represents red dye
+     */
     RED((byte) 0xE),
+    /**
+     * Represents black dye
+     */
     BLACK((byte) 0xF);
 
     private final byte data;
@@ -32,10 +80,21 @@ public enum DyeColor {
         this.data = data;
     }
 
+    /**
+     * Gets the associated data value representing this color
+     *
+     * @return A byte containing the data value of this color
+     */
     public byte getData() {
         return data;
     }
 
+    /**
+     * Gets the DyeColor with the given data value
+     *
+     * @param data Data value to fetch
+     * @return The {@link DyeColor} representing the given value, or null if it doesn't exist
+     */
     public static DyeColor getByData(final byte data) {
         return colors.get(data);
     }
diff --git a/src/main/java/org/bukkit/Location.java b/src/main/java/org/bukkit/Location.java
index afe6d71b..2d24bded 100644
--- a/src/main/java/org/bukkit/Location.java
+++ b/src/main/java/org/bukkit/Location.java
@@ -15,10 +15,28 @@ public class Location implements Cloneable {
     private float pitch;
     private float yaw;
 
+    /**
+     * Constructs a new Location with the given coordinates
+     *
+     * @param world The world in which this location resides
+     * @param x The x-coordinate of this new location
+     * @param y The y-coordinate of this new location
+     * @param z The z-coordinate of this new location
+     */
     public Location(final World world, final double x, final double y, final double z) {
         this(world, x, y, z, 0, 0);
     }
 
+    /**
+     * Constructs a new Location with the given coordinates and direction
+     *
+     * @param world The world in which this location resides
+     * @param x The x-coordinate of this new location
+     * @param y The y-coordinate of this new location
+     * @param z The z-coordinate of this new location
+     * @param yaw The absolute rotation on the x-plane, in degrees
+     * @param pitch The absolute rotation on the y-plane, in degrees
+     */
     public Location(final World world, final double x, final double y, final double z, final float yaw, final float pitch) {
         this.world = world;
         this.x = x;
@@ -242,6 +260,11 @@ public class Location implements Cloneable {
         return "Location{" + "world=" + world + "x=" + x + "y=" + y + "z=" + z + "pitch=" + pitch + "yaw=" + yaw + '}';
     }
 
+    /**
+     * Constructs a new {@link Vector} based on this Location
+     *
+     * @return New Vector containing the coordinates represented by this Location
+     */
     public Vector toVector() {
         return new Vector(x, y, z);
     }
diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
index 77ef9099..37950a62 100644
--- a/src/main/java/org/bukkit/World.java
+++ b/src/main/java/org/bukkit/World.java
@@ -17,54 +17,52 @@ import org.bukkit.entity.Arrow;
 import org.bukkit.entity.Boat;
 
 /**
- * Represents a world.
- *
- * Currently there is only one world in the default Minecraft spec, but this
- * may change with the addition of a functional Nether world
+ * Represents a world, which may contain entities, chunks and blocks
  */
 public interface World {
     /**
-     * Gets the block at the given location
-     *
-     * This block will always represent the latest state
+     * Gets the {@link Block} at the given coordinates
      *
      * @param x X-coordinate of the block
      * @param y Y-coordinate of the block
      * @param z Z-coordinate of the block
-     * @return Block at the given location
+     * @return Block at the given coordinates
+     * @see #getBlockTypeIdAt(int, int, int) Returns the current type ID of the block
      */
     public Block getBlockAt(int x, int y, int z);
     
     /**
-     * Gets the block at the given location
-     *
-     * This block will always represent the latest state
+     * Gets the {@link Block} at the given {@link Location}
      *
      * @param location Location of the block
      * @return Block at the given location
+     * @see #getBlockTypeIdAt(org.bukkit.Location) Returns the current type ID of the block
      */
     public Block getBlockAt(Location location);
 
     /**
-     * Gets the block type-id at the given location
+     * Gets the block type ID at the given coordinates
      *
      * @param x X-coordinate of the block
      * @param y Y-coordinate of the block
      * @param z Z-coordinate of the block
-     * @return TypeId of the block at the given location
+     * @return Type ID of the block at the given coordinates
+     * @see #getBlockAt(int, int, int) Returns a live Block object at the given location
      */
     public int getBlockTypeIdAt(int x, int y, int z);
 
     /**
-     * Gets the block type-id at the given location
+     * Gets the block type ID at the given {@link Location}
      *
      * @param location Location of the block
-     * @return TypeId of the block at the given location
+     * @return Type ID of the block at the given location
+     * @see #getBlockAt(org.bukkit.Location) Returns a live Block object at the given location
      */
     public int getBlockTypeIdAt(Location location);
 
     /**
-     * Gets the highest non-air coordinate at the given (x,z) location
+     * Gets the highest non-air coordinate at the given coordinates
+     *
      * @param x X-coordinate of the blocks
      * @param z Z-coordinate of the blocks
      * @return Y-coordinate of the highest non-air block
@@ -72,23 +70,24 @@ public interface World {
     public int getHighestBlockYAt(int x, int z);
 
     /**
-     * Gets the highest non-air coordinate at the given location
+     * Gets the highest non-air coordinate at the given {@link Location}
+     *
      * @param location Location of the blocks
      * @return Y-coordinate of the highest non-air block
      */
     public int getHighestBlockYAt(Location location);
 
     /**
-     * Gets the chunk at the given location
+     * Gets the {@link Chunk} at the given coordinates
      *
      * @param x X-coordinate of the chunk
      * @param z Z-coordinate of the chunk
-     * @return Chunk at the given location
+     * @return Chunk at the given coordinates
      */
     public Chunk getChunkAt(int x, int z);
 
     /**
-     * Gets the chunk at the given location
+     * Gets the {@link Chunk} at the given {@link Location}
      *
      * @param location Location of the chunk
      * @return Chunk at the given location
@@ -96,35 +95,37 @@ public interface World {
     public Chunk getChunkAt(Location location);
 
     /**
-     * Gets the chunk which contains the given block
+     * Gets the {@link Chunk} that contains the given {@link Block}
      *
-     * @param block Block to get the parent chunk from
-     * @return Chunk that contains the given block
+     * @param block Block to get the containing chunk from
+     * @return The chunk that contains the given block
      */
     public Chunk getChunkAt(Block block);
 
     /**
-     * Checks if the specified chunk is loaded
+     * Checks if the specified {@link Chunk} is loaded
      *
+     * @param chunk The chunk to check
      * @return true if the chunk is loaded, otherwise false
      */
     public boolean isChunkLoaded(Chunk chunk);
 
     /**
-     * Gets an array of all loaded chunks
+     * Gets an array of all loaded {@link Chunk}s
      *
-     * @return Chunk array of all loaded chunks
+     * @return Chunk[] containing all loaded chunks
      */
     public Chunk[] getLoadedChunks();
 
     /**
-     * Loads the specified chunk
+     * Loads the specified {@link Chunk}
      *
+     * @param chunk The chunk to load
      */
     public void loadChunk(Chunk chunk);
 
     /**
-     * Checks if the chunk at the specified coordinates is loaded
+     * Checks if the {@link Chunk} at the specified coordinates is loaded
      *
      * @param x X-coordinate of the chunk
      * @param z Z-coordinate of the chunk
@@ -133,58 +134,74 @@ public interface World {
     public boolean isChunkLoaded(int x, int z);
 
     /**
-     * Loads the chunk at the specified coordinates and generates the chunk when it is non-existing
+     * Loads the {@link Chunk} at the specified coordinates
+     *
+     * If the chunk does not exist, it will be generated.
+     * This method is analogous to {@link #loadChunk(int, int, boolean)} where generate is true.
+     *
      * @param x X-coordinate of the chunk
      * @param z Z-coordinate of the chunk
      */
     public void loadChunk(int x, int z);
 
     /**
-     * Loads the chunk at the specified coordinates and generates the chunk when it is non-existing if generate is enabled
+     * Loads the {@link Chunk} at the specified coordinates
+     *
      * @param x X-coordinate of the chunk
      * @param z Z-coordinate of the chunk
-     * @param generate Controls whether non-generated chunks are generated
-     * @return Whether the chunk has loaded
+     * @param generate Whether or not to generate a chunk if it doesn't already exist
+     * @return true if the chunk has loaded successfully, otherwise false
      */
     public boolean loadChunk(int x, int z, boolean generate);
 
     /**
-     * Safely unloads and saves the chunk at the specified coordinates
+     * Safely unloads and saves the {@link Chunk} at the specified coordinates
+     *
+     * This method is analogous to {@link #unloadChunk(int, int, boolean, boolean)} where safe and saveis true
+     *
      * @param x X-coordinate of the chunk
      * @param z Z-coordinate of the chunk
-     * @return Whether the chunk was actually unloaded
+     * @return true if the chunk has unloaded successfully, otherwise false
      */
     public boolean unloadChunk(int x, int z);
 
     /**
-     * Safely unloads and optionally saves the chunk at the specified coordinates
+     * Safely unloads and optionally saves the {@link Chunk} at the specified coordinates
+     *
+     * This method is analogous to {@link #unloadChunk(int, int, boolean, boolean)} where save is true
+     *
      * @param x X-coordinate of the chunk
      * @param z Z-coordinate of the chunk
-     * @param save Controls whether the chunk is saved
-     * @return Whether the chunk was actually unloaded
+     * @param save Whether or not to save the chunk
+     * @return true if the chunk has unloaded successfully, otherwise false
      */
     public boolean unloadChunk(int x, int z, boolean save);
 
     /**
-     * Unloads and optionally saves the chunk at the specified coordinates
+     * Unloads and optionally saves the {@link Chunk} at the specified coordinates
+     *
      * @param x X-coordinate of the chunk
      * @param z Z-coordinate of the chunk
      * @param save Controls whether the chunk is saved
      * @param safe Controls whether to unload the chunk when players are nearby
-     * @return Whether the chunk was actually unloaded
+     * @return true if the chunk has unloaded successfully, otherwise false
      */
     public boolean unloadChunk(int x, int z, boolean save, boolean safe);
 
     /**
-     * Safely queues the chunk at the specified coordinates for unloading
+     * Safely queues the {@link Chunk} at the specified coordinates for unloading
+     *
+     * This method is analogous to {@link #unloadChunkRequest(int, int, boolean)} where safe is true
+     *
      * @param x X-coordinate of the chunk
      * @param z Z-coordinate of the chunk
-     * @return Whether the chunk was actually queued
+     * @return true is the queue attempt was successful, otherwise false
      */
     public boolean unloadChunkRequest(int x, int z);
 
     /**
-     * Queues the chunk at the specified coordinates for unloading
+     * Queues the {@link Chunk} at the specified coordinates for unloading
+     *
      * @param x X-coordinate of the chunk
      * @param z Z-coordinate of the chunk
      * @param safe Controls whether to queue the chunk when players are nearby
@@ -193,171 +210,177 @@ public interface World {
     public boolean unloadChunkRequest(int x, int z, boolean safe);
 
     /**
-     * Drop an item exactly at the specified location.
+     * Drops an item at the specified {@link Location}
      *
-     * @param loc
-     * @param item
-     * @return dropped item entity
+     * @param location Location to drop the item
+     * @param item ItemStack to drop
+     * @return ItemDrop entity created as a result of this method
      */
-    public ItemDrop dropItem(Location loc, ItemStack item);
+    public ItemDrop dropItem(Location location, ItemStack item);
 
     /**
-     * Drop an item as if it was mined (randomly placed).
+     * Drops an item at the specified {@link Location} with a random offset
      *
-     * @param loc
-     * @param item
-     * @return dropped item entity
+     * @param location Location to drop the item
+     * @param item ItemStack to drop
+     * @return ItemDrop entity created as a result of this method
      */
-    public ItemDrop dropItemNaturally(Location loc, ItemStack item);
+    public ItemDrop dropItemNaturally(Location location, ItemStack item);
 
     /**
-     * Spawns an arrow.
+     * Creates an {@link Arrow} entity at the given {@link Location}
      *
-     * @param loc
-     * @param velocity velocity vector
-     * @param speed a reasonable speed is 0.6
-     * @param spread a reasonable spread is 12
-     * @return the arrow entity
+     * @param location Location to spawn the arrow
+     * @param velocity Velocity to shoot the arrow in
+     * @param speed Speed of the arrow. A recommend speed is 0.6
+     * @param spread Spread of the arrow. A recommend spread is 12
+     * @return Arrow entity spawned as a result of this method
      */
-    public Arrow spawnArrow(Location loc, Vector velocity, float speed, float spread);
+    public Arrow spawnArrow(Location location, Vector velocity, float speed, float spread);
 
     /**
-     * Spawns a tree at a location.
+     * Creates a tree at the given {@link Location}
      *
-     * @param loc
-     * @param type
-     * @return whether the tree was created
+     * @param location Location to spawn the tree
+     * @param type Type of the tree to create
+     * @return true if the tree was created successfully, otherwise false
      */
-    public boolean generateTree(Location loc, TreeType type);
+    public boolean generateTree(Location location, TreeType type);
 
     /**
-     * Spawns a tree at a location.
+     * Creates a tree at the given {@link Location}
      *
-     * @param loc
-     * @param type
-     * @param delegate
-     * @return whether the tree was created
+     * @param location Location to spawn the tree
+     * @param type Type of the tree to create
+     * @param delegate A class to call for each block changed as a result of this method
+     * @return true if the tree was created successfully, otherwise false
      */
     public boolean generateTree(Location loc, TreeType type, BlockChangeDelegate delegate);
 
     /**
-     * Spawns a regular passenger minecart.
+     * Creates a regular passenger minecart at the given {@link Location}
      *
-     * @param loc
-     * @return
+     * @param location Location to spawn the minecart
+     * @return Minecart created as a result of this method
      */
-    public Minecart spawnMinecart(Location loc);
+    public Minecart spawnMinecart(Location location);
 
     /**
-     * Spawns a storage minecart.
+     * Creates a storage minecart at the given {@link Location}
      *
-     * @param loc
-     * @return
+     * @param location Location to spawn the minecart
+     * @return StorageMinecart created as a result of this method
      */
     public StorageMinecart spawnStorageMinecart(Location loc);
 
     /**
-     * Spawns a powered minecart.
+     * Creates a powered minecart at the given {@link Location}
      *
-     * @param loc
-     * @return
+     * @param location Location to spawn the minecart
+     * @return PoweredMinecart created as a result of this method
      */
     public PoweredMinecart spawnPoweredMinecart(Location loc);
 
     /**
-     * Spawn a boat.
+     * Creates a boat at the given {@link Location}
      *
-     * @param loc
-     * @return
+     * @param location Location to spawn the boat
+     * @return Boat created as a result of this method
      */
     public Boat spawnBoat(Location loc);
 
     /**
-     * Spawn a creature at the given location.
-     * 
-     * @param loc The location to spawn at.
-     * @param creatureType The creature to spawn.
+     * Creates a creature at the given {@link Location}
      * 
-     * @return The Creature if it was spawned, null otherwise.
+     * @param loc The location to spawn the creature
+     * @param type The creature to spawn
+     * @return Resulting Creature of this method, or null if it was unsuccessful
      */
-    public Creature spawnCreature(Location loc, CreatureType creatureType);
+    public Creature spawnCreature(Location loc, CreatureType type);
 
     /**
-     * Get a list of all entities.
+     * Get a list of all entities in this World
      *
-     * @return
+     * @return A List of all Entities currently residing in this world
      */
     public List<Entity> getEntities();
 
     /**
-     * Get a list of all living entities.
+     * Get a list of all living entities in this World
      *
-     * @return
+     * @return A List of all LivingEntities currently residing in this world
      */
     public List<LivingEntity> getLivingEntities();
 
     /**
-     * Gets the name of this world. This is not guaranteed to be unique.
+     * Gets the unique name of this world
      *
      * @return Name of this world
      */
     public String getName();
 
     /**
-     * Gets a semi-unique identifier for this world. While it is highly unlikely
-     * that this may be shared with another World, it is not guaranteed to be
-     * unique.
+     * Gets a semi-unique identifier for this world.
+     * 
+     * While it is highly unlikely that this may be shared with another World,
+     * it is not guaranteed to be unique
      *
      * @return Id of this world
      */
     public long getId();
 
     /**
-     * Gets the default spawn location.
+     * Gets the default spawn {@link Location} of this world
+     *
+     * @return The spawn location of this world
      */
     public Location getSpawnLocation();
 
     /**
-     * Gets the relative in-game time on this world (in hours*1000)
+     * Gets the relative in-game time of this world.
+     *
+     * The relative time is analogous to hours * 1000
      *
-     * @return The current relative time in hours*1000
-     * @see getFullTime
+     * @return The current relative time
+     * @see #getFullTime() Returns an absolute time of this world
      */
     public long getTime();
 
     /**
-     * Sets the relative in-game time on the server (in hours*1000)<br />
-     * <br />
+     * Sets the relative in-game time on the server.
+     *
+     * The relative time is analogous to hours * 1000
+     * <br /><br />
      * Note that setting the relative time below the current relative time will
      * actually move the clock forward a day. If you require to rewind time, please
      * see setFullTime
      *
      * @param time The new relative time to set the in-game time to (in hours*1000)
-     * @see setFullTime
+     * @see #setFullTime(long) Sets the absolute time of this world
      */
     public void setTime(long time);
 
     /**
-     * Gets the full in-game time on this world (in hours*1000)
+     * Gets the full in-game time on this world
      *
-     * @return The current time in hours*1000
-     * @see setTime
+     * @return The current absolute time
+     * @see #getTime() Returns a relative time of this world
      */
     public long getFullTime();
 
     /**
-     * Sets the in-game time on the server (in hours*1000)<br />
-     * <br />
+     * Sets the in-game time on the server
+     * <br /><br />
      * Note that this sets the full time of the world, which may cause adverse
      * effects such as breaking redstone clocks and any scheduled events
      *
-     * @param time The new time to set the in-game time to (in hours*1000)
-     * @see setTime
+     * @param time The new absolute time to set this world to
+     * @see #setTime(long) Sets the relative time of this world
      */
     public void setFullTime(long time);
 
     /**
-     * Gets the environment type of this world
+     * Gets the {@link Environment} type of this world
      *
      * @return This worlds Environment type
      */