Improve javadoc in 26 files.

Addresses:
BUKKIT-1643, BUKKIT-1868, BUKKIT-1846, BUKKIT-2632, BUKKIT-3196,
BUKKIT-3187, BUKKIT-3198, BUKKIT-3200, BUKKIT-3201 and BUKKIT-3417.

src/main/java/org/bukkit/ChatColor.java

@@ -193,7 +193,7 @@ public enum ChatColor {
     /**
      * Translates a string using an alternate color code character into a string that uses the internal
      * ChatColor.COLOR_CODE color code character. The alternate color code character will only be replaced
-     * if it is immediately followed by 0-9, A-F, or a-f.
+     * if it is immediately followed by 0-9, A-F, a-f, K-O, k-o, R or r.
      *
      * @param altColorChar The alternate color code character to replace. Ex: &
      * @param textToTranslate Text containing the alternate color code character.

src/main/java/org/bukkit/Color.java

@@ -157,8 +157,8 @@ public final class Color implements ConfigurationSerializable {
 
     private Color(int red, int green, int blue) {
         Validate.isTrue(red >= 0 && red <= BIT_MASK, "Red is not between 0-255: ", red);
-        Validate.isTrue(green >= 0 && green <= BIT_MASK, "Red is not between 0-255: ", green);
+        Validate.isTrue(green >= 0 && green <= BIT_MASK, "Green is not between 0-255: ", green);
-        Validate.isTrue(blue >= 0 && blue <= BIT_MASK, "Red is not between 0-255: ", blue);
+        Validate.isTrue(blue >= 0 && blue <= BIT_MASK, "Blue is not between 0-255: ", blue);
 
         this.red = (byte) red;
         this.green = (byte) green;

src/main/java/org/bukkit/Server.java

@@ -634,19 +634,19 @@ public interface Server extends PluginMessageRecipient {
 
     /**
      * Gets user-specified limit for number of monsters that can spawn in a chunk
-     * @returns The monster spawn limit
+     * @return The monster spawn limit
      */
     int getMonsterSpawnLimit();
 
     /**
      * Gets user-specified limit for number of animals that can spawn in a chunk
-     * @returns The animal spawn limit
+     * @return The animal spawn limit
      */
     int getAnimalSpawnLimit();
 
     /**
      * Gets user-specified limit for number of water animals that can spawn in a chunk
-     * @returns The water animal spawn limit
+     * @return The water animal spawn limit
      */
     int getWaterAnimalSpawnLimit();
 
@@ -664,7 +664,7 @@ public interface Server extends PluginMessageRecipient {
     /**
      * Gets the message that is displayed on the server list
      *
-     * @returns the servers MOTD
+     * @return the servers MOTD
      */
     String getMotd();
 

src/main/java/org/bukkit/World.java

@@ -957,7 +957,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
 
     /**
      * Gets limit for number of monsters that can spawn in a chunk in this world
-     * @returns The monster spawn limit
+     * @return The monster spawn limit
      */
     int getMonsterSpawnLimit();
 
@@ -971,7 +971,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
 
     /**
      * Gets the limit for number of animals that can spawn in a chunk in this world
-     * @returns The animal spawn limit
+     * @return The animal spawn limit
      */
     int getAnimalSpawnLimit();
 
@@ -985,7 +985,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
 
     /**
      * Gets the limit for number of water animals that can spawn in a chunk in this world
-     * @returns The water animal spawn limit
+     * @return The water animal spawn limit
      */
     int getWaterAnimalSpawnLimit();
 

src/main/java/org/bukkit/command/defaults/TeleportCommand.java

@@ -17,8 +17,8 @@ public class TeleportCommand extends VanillaCommand {
 
     public TeleportCommand() {
         super("tp");
-        this.description = "Teleports the given player to another player or location";
+        this.description = "Teleports the given player (or yourself) to another player or coordinates";
-        this.usageMessage = "/tp [player] <target>\n/tp [player] <x> <y> <z>";
+        this.usageMessage = "/tp [player] <target> and/or <x> <y> <z>";
         this.setPermission("bukkit.command.teleport");
     }
 

src/main/java/org/bukkit/command/defaults/WhitelistCommand.java

@@ -18,7 +18,7 @@ public class WhitelistCommand extends VanillaCommand {
 
     public WhitelistCommand() {
         super("whitelist");
-        this.description = "Prevents the specified player from using this server";
+        this.description = "Manages the list of players allowed to use this server";
         this.usageMessage = "/whitelist (add|remove) <player>\n/whitelist (on|off|list|reload)";
         this.setPermission("bukkit.command.whitelist.reload;bukkit.command.whitelist.enable;bukkit.command.whitelist.disable;bukkit.command.whitelist.list;bukkit.command.whitelist.add;bukkit.command.whitelist.remove");
     }

src/main/java/org/bukkit/configuration/ConfigurationSection.java

@@ -409,7 +409,7 @@ public interface ConfigurationSection {
      * <p />
      * If the List does not exist but a default value has been specified, this
      * will return the default value. If the List does not exist and no default
-     * value was specified, this will return null.
+     * value was specified, this will return an empty List.
      * <p />
      * This method will attempt to cast any values into a String if possible, but may
      * miss any values out if they are not compatible.
@@ -424,7 +424,7 @@ public interface ConfigurationSection {
      * <p />
      * If the List does not exist but a default value has been specified, this
      * will return the default value. If the List does not exist and no default
-     * value was specified, this will return null.
+     * value was specified, this will return an empty List.
      * <p />
      * This method will attempt to cast any values into a Integer if possible, but may
      * miss any values out if they are not compatible.
@@ -439,7 +439,7 @@ public interface ConfigurationSection {
      * <p />
      * If the List does not exist but a default value has been specified, this
      * will return the default value. If the List does not exist and no default
-     * value was specified, this will return null.
+     * value was specified, this will return an empty List.
      * <p />
      * This method will attempt to cast any values into a Boolean if possible, but may
      * miss any values out if they are not compatible.
@@ -454,7 +454,7 @@ public interface ConfigurationSection {
      * <p />
      * If the List does not exist but a default value has been specified, this
      * will return the default value. If the List does not exist and no default
-     * value was specified, this will return null.
+     * value was specified, this will return an empty List.
      * <p />
      * This method will attempt to cast any values into a Double if possible, but may
      * miss any values out if they are not compatible.
@@ -469,7 +469,7 @@ public interface ConfigurationSection {
      * <p />
      * If the List does not exist but a default value has been specified, this
      * will return the default value. If the List does not exist and no default
-     * value was specified, this will return null.
+     * value was specified, this will return an empty List.
      * <p />
      * This method will attempt to cast any values into a Float if possible, but may
      * miss any values out if they are not compatible.
@@ -484,7 +484,7 @@ public interface ConfigurationSection {
      * <p />
      * If the List does not exist but a default value has been specified, this
      * will return the default value. If the List does not exist and no default
-     * value was specified, this will return null.
+     * value was specified, this will return an empty List.
      * <p />
      * This method will attempt to cast any values into a Long if possible, but may
      * miss any values out if they are not compatible.
@@ -499,7 +499,7 @@ public interface ConfigurationSection {
      * <p />
      * If the List does not exist but a default value has been specified, this
      * will return the default value. If the List does not exist and no default
-     * value was specified, this will return null.
+     * value was specified, this will return an empty List.
      * <p />
      * This method will attempt to cast any values into a Byte if possible, but may
      * miss any values out if they are not compatible.
@@ -514,7 +514,7 @@ public interface ConfigurationSection {
      * <p />
      * If the List does not exist but a default value has been specified, this
      * will return the default value. If the List does not exist and no default
-     * value was specified, this will return null.
+     * value was specified, this will return an empty List.
      * <p />
      * This method will attempt to cast any values into a Character if possible, but may
      * miss any values out if they are not compatible.
@@ -529,7 +529,7 @@ public interface ConfigurationSection {
      * <p />
      * If the List does not exist but a default value has been specified, this
      * will return the default value. If the List does not exist and no default
-     * value was specified, this will return null.
+     * value was specified, this will return an empty List.
      * <p />
      * This method will attempt to cast any values into a Short if possible, but may
      * miss any values out if they are not compatible.
@@ -544,7 +544,7 @@ public interface ConfigurationSection {
      * <p />
      * If the List does not exist but a default value has been specified, this
      * will return the default value. If the List does not exist and no default
-     * value was specified, this will return null.
+     * value was specified, this will return an empty List.
      * <p />
      * This method will attempt to cast any values into a Map if possible, but may
      * miss any values out if they are not compatible.

src/main/java/org/bukkit/entity/Entity.java

@@ -20,7 +20,7 @@ public interface Entity extends Metadatable {
     /**
      * Gets the entity's current position
      *
-     * @return Location containing the position of this entity
+     * @return a new copy of Location containing the position of this entity
      */
     public Location getLocation();
 

src/main/java/org/bukkit/entity/EntityType.java

@@ -3,27 +3,79 @@ package org.bukkit.entity;
 import java.util.HashMap;
 import java.util.Map;
 
+import org.bukkit.inventory.ItemStack;
 import org.bukkit.Location;
 import org.bukkit.World;
 
 public enum EntityType {
     // These strings MUST match the strings in nms.EntityTypes and are case sensitive.
+    /**
+     * An item resting on the ground.
+     *
+     * Spawn with {@link World#dropItem(Location, ItemStack)}
+     * or {@link World#dropItemNaturally(Location, ItemStack)}
+     */
     DROPPED_ITEM("Item", Item.class, 1, false),
+    /**
+     * An experience orb.
+     */
     EXPERIENCE_ORB("XPOrb", ExperienceOrb.class, 2),
+    /**
+     * A painting on a wall.
+     */
     PAINTING("Painting", Painting.class, 9),
+    /**
+     * An arrow projectile; may get stuck in the ground.
+     */
     ARROW("Arrow", Arrow.class, 10),
+    /**
+     * A flyinf snowball.
+     */
     SNOWBALL("Snowball", Snowball.class, 11),
+    /**
+     * A flying large fireball, as thrown by a Ghast for example.
+     */
     FIREBALL("Fireball", LargeFireball.class, 12),
+    /**
+     * A flying small fireball, such as thrown by a Blaze or player.
+     */
     SMALL_FIREBALL("SmallFireball", SmallFireball.class, 13),
+    /**
+     * A flying ender pearl.
+     */
     ENDER_PEARL("ThrownEnderpearl", EnderPearl.class, 14),
+    /**
+     * An ender eye signal.
+     */
     ENDER_SIGNAL("EyeOfEnderSignal", EnderSignal.class, 15),
+    /**
+     * A flying experience bottle.
+     */
     THROWN_EXP_BOTTLE("ThrownExpBottle", ThrownExpBottle.class, 17),
+    /**
+     * An item frame on a wall.
+     */
     ITEM_FRAME("ItemFrame", ItemFrame.class, 18),
+    /**
+     * A flying wither skull projectile.
+     */
     WITHER_SKULL("WitherSkull", WitherSkull.class, 19),
+    /**
+     * Primed TNT that is about to explode.
+     */
     PRIMED_TNT("PrimedTnt", TNTPrimed.class, 20),
+    /**
+     * A block that is going to or is about to fall.
+     */
     FALLING_BLOCK("FallingSand", FallingBlock.class, 21, false),
     FIREWORK("FireworksRocketEntity", Firework.class, 22, false),
+    /**
+     * A placed minecart of any type.
+     */
     MINECART("Minecart", Minecart.class, 40),
+    /**
+     * A placed boat.
+     */
     BOAT("Boat", Boat.class, 41),
     CREEPER("Creeper", Creeper.class, 50),
     SKELETON("Skeleton", Skeleton.class, 51),
@@ -55,11 +107,22 @@ public enum EntityType {
     VILLAGER("Villager", Villager.class, 120),
     ENDER_CRYSTAL("EnderCrystal", EnderCrystal.class, 200),
     // These don't have an entity ID in nms.EntityTypes.
+    /**
+     * A flying splash potion.
+     */
     SPLASH_POTION(null, ThrownPotion.class, -1, false),
+    /**
+     * A flying chicken egg.
+     */
     EGG(null, Egg.class, -1, false),
+    /**
+     * A fishing line and bobber.
+     */
     FISHING_HOOK(null, Fish.class, -1, false),
     /**
-     * Spawn with {@link World#strikeLightning(org.bukkit.Location)}.
+     * A bolt of lightning.
+     *
+     * Spawn with {@link World#strikeLightning(Location)}.
      */
     LIGHTNING(null, LightningStrike.class, -1, false),
     WEATHER(null, Weather.class, -1, false),
@@ -130,7 +193,7 @@ public enum EntityType {
     }
 
     /**
-     * Some entities cannot be spawned using {@link World#spawnCreature(Location, EntityType)}
+     * Some entities cannot be spawned using {@link World#spawnEntity(Location, EntityType)}
      * or {@link World#spawn(Location, Class)}, usually
      * because they require additional information in order to spawn.
      * @return False if the entity type cannot be spawned

src/main/java/org/bukkit/event/block/BlockIgniteEvent.java

@@ -71,7 +71,7 @@ public class BlockIgniteEvent extends BlockEvent implements Cancellable {
          */
         LIGHTNING,
         /**
-         * Block ignition caused by a player using a fireball.
+         * Block ignition caused by an entity using a fireball.
          */
         FIREBALL,
     }

src/main/java/org/bukkit/event/player/PlayerFishEvent.java

@@ -84,11 +84,11 @@ public class PlayerFishEvent extends PlayerEvent implements Cancellable {
     public enum State {
 
         /**
-         * When a player is fishing
+         * When a player is fishing, ie casting the line out.
          */
         FISHING,
         /**
-         * When a player has successfully caught a fish
+         * When a player has successfully caught a fish and is reeling it in.
          */
         CAUGHT_FISH,
         /**
@@ -96,7 +96,7 @@ public class PlayerFishEvent extends PlayerEvent implements Cancellable {
          */
         CAUGHT_ENTITY,
         /**
-         * When a bobber is stuck in the grund
+         * When a bobber is stuck in the ground
          */
         IN_GROUND,
         /**

src/main/java/org/bukkit/event/server/ServerListPingEvent.java

@@ -60,7 +60,7 @@ public class ServerListPingEvent extends ServerEvent {
     /**
      * Get the maximum number of players sent.
      *
-     * @return the the maximum number of player
+     * @return the maximum number of players
      */
     public int getMaxPlayers() {
         return maxPlayers;

src/main/java/org/bukkit/inventory/EntityEquipment.java

@@ -201,9 +201,9 @@ public interface EntityEquipment {
     void setBootsDropChance(float chance);
 
     /**
-     * Get the entity this CreatureEquipment belongs to
+     * Get the entity this EntityEquipment belongs to
      *
-     * @return the entity this CreatureEquipment belongs to
+     * @return the entity this EntityEquipment belongs to
      */
     Entity getHolder();
 }

src/main/java/org/bukkit/inventory/Inventory.java

@@ -16,12 +16,14 @@ public interface Inventory extends Iterable<ItemStack> {
     /**
      * Returns the size of the inventory
      *
-     * @return The inventory size
+     * @return The size of the inventory
      */
     public int getSize();
 
     /**
-     * @return The maximum stack size for items in this inventory.
+     * Returns the maximum stack size for an ItemStack in this inventory.
+     *
+     * @return The maximum size for an ItemStack in this inventory.
      */
     public int getMaxStackSize();
 
@@ -41,14 +43,14 @@ public interface Inventory extends Iterable<ItemStack> {
     public void setMaxStackSize(int size);
 
     /**
-     * Return the name of the inventory
+     * Returns the name of the inventory
      *
-     * @return The inventory name
+     * @return The String with the name of the inventory
      */
     public String getName();
 
     /**
-     * Get the ItemStack found in the slot at the given index
+     * Returns the ItemStack found in the slot at the given index
      *
      * @param index The index of the Slot's ItemStack to return
      * @return The ItemStack in the slot
@@ -56,7 +58,7 @@ public interface Inventory extends Iterable<ItemStack> {
     public ItemStack getItem(int index);
 
     /**
-     * Stores the ItemStack at the given index
+     * Stores the ItemStack at the given index of the inventory.
      *
      * @param index The index where to put the ItemStack
      * @param item The ItemStack to set
@@ -65,11 +67,15 @@ public interface Inventory extends Iterable<ItemStack> {
 
     /**
      * Stores the given ItemStacks in the inventory.
-     * This will try to fill existing stacks and empty slots as good as it can.
+     * This will try to fill existing stacks and empty slots as well as it can.
-     * It will return a HashMap of what it couldn't fit.
+     * <p />
+     * The returned HashMap contains what it couldn't store, where the key is the
+     * index of the parameter, and the value is the ItemStack at that index
+     * of the variadic parameter. If all items are stored, it will return an
+     * empty HashMap.
      *
      * @param items The ItemStacks to add
-     * @return The items that didn't fit.
+     * @return A HashMap containing items that didn't fit.
      * @throws IllegalArgumentException if items or any element in it is null
      */
     public HashMap<Integer, ItemStack> addItem(ItemStack... items) throws IllegalArgumentException;
@@ -78,23 +84,29 @@ public interface Inventory extends Iterable<ItemStack> {
      * Removes the given ItemStacks from the inventory.
      * <p />
      * It will try to remove 'as much as possible' from the types and amounts you
-     * give as arguments. It will return a HashMap of what it couldn't remove.
+     * give as arguments.
+     * <p />
+     * The returned HashMap contains what it couldn't remove, where the key is the
+     * index of the parameter, and the value is the ItemStack at that index of the
+     * variadic parameter. If all the given ItemStacks are removed, it will return
+     * an empty HashMap.
      *
      * @param items The ItemStacks to remove
-     * @return The items that couldn't be removed.
+     * @return A HashMap containing items that couldn't be removed.
      * @throws IllegalArgumentException if items is null
      */
     public HashMap<Integer, ItemStack> removeItem(ItemStack... items) throws IllegalArgumentException;
 
     /**
-     * Gets all ItemStacks from the inventory.
+     * Returns all ItemStacks from the inventory
      *
-     * @return All the ItemStacks from all slots
+     * @return An array of ItemStacks from the inventory.
      */
     public ItemStack[] getContents();
 
     /**
-     * Set the inventory's contents.
+     * Completely replaces the inventory's contents. Removes all existing
+     * contents and replaces it with the ItemStacks given in the array.
      *
      * @param items A complete replacement for the contents; the length must be less than or equal to {@link #getSize()}.
      * @throws IllegalArgumentException If the array has more items than the inventory.
@@ -102,25 +114,25 @@ public interface Inventory extends Iterable<ItemStack> {
     public void setContents(ItemStack[] items) throws IllegalArgumentException;
 
     /**
-     * Check if the inventory contains any ItemStacks with the given materialId.
+     * Checks if the inventory contains any ItemStacks with the given materialId
      *
      * @param materialId The materialId to check for
-     * @return If any ItemStacks were found
+     * @return true if an ItemStack in this inventory contains the materialId
      */
     public boolean contains(int materialId);
 
     /**
-     * Check if the inventory contains any ItemStacks with the given material.
+     * Checks if the inventory contains any ItemStacks with the given material.
      *
      * @param material The material to check for
-     * @return If any ItemStacks were found
+     * @return true if an ItemStack is found with the given Material
      * @throws IllegalArgumentException if material is null
      */
     public boolean contains(Material material) throws IllegalArgumentException;
 
     /**
-     * Check if the inventory contains any ItemStacks matching the given ItemStack.
+     * Checks if the inventory contains any ItemStacks matching the given ItemStack.
-     * This will only match if both the type and the amount of the stack match.
+     * This will only return true if both the type and the amount of the stack match.
      *
      * @param item The ItemStack to match against
      * @return false if item is null, true if any exactly matching ItemStacks were found
@@ -128,16 +140,16 @@ public interface Inventory extends Iterable<ItemStack> {
     public boolean contains(ItemStack item);
 
     /**
-     * Check if the inventory contains any ItemStacks with the given materialId, adding to at least the minimum amount specified.
+     * Checks if the inventory contains any ItemStacks with the given materialId, adding to at least the minimum amount specified.
      *
      * @param materialId The materialId to check for
      * @param amount The minimum amount to look for
-     * @return true if amount is less than 1, true if enough ItemStacks were found to add to the given amount
+     * @return true if this contains any matching ItemStack with the given materialId and amount
      */
     public boolean contains(int materialId, int amount);
 
     /**
-     * Check if the inventory contains any ItemStacks with the given material, adding to at least the minimum amount specified.
+     * Checks if the inventory contains any ItemStacks with the given material, adding to at least the minimum amount specified.
      *
      * @param material The material to check for
      * @param amount The minimum amount
@@ -147,7 +159,8 @@ public interface Inventory extends Iterable<ItemStack> {
     public boolean contains(Material material, int amount) throws IllegalArgumentException;
 
     /**
-     * Check if the inventory contains the amount of ItemStacks exactly matching the given ItemStack.
+     * Checks if the inventory contains any ItemStacks matching the given ItemStack and at least the minimum amount specified
+     * This will only match if both the type and the amount of the stack match
      *
      * @param item The ItemStack to match against
      * @param amount The amount of stacks to find
@@ -156,8 +169,12 @@ public interface Inventory extends Iterable<ItemStack> {
     public boolean contains(ItemStack item, int amount);
 
     /**
-     * Check if the inventory contains the specified amount of a similar ItemStack.
+     * Returns a HashMap with all slots and ItemStacks in the inventory with
-     * This ignores the size of the stack, using the {@link ItemStack#isSimilar(ItemStack)} method.
+     * given materialId.
+     * <p />
+     * The HashMap contains entries where, the key is the slot index, and the
+     * value is the ItemStack in that slot. If no matching ItemStack with the
+     * given materialId is found, an empty map is returned.
      *
      * @param item The ItemStack to match against
      * @param amount The minimum amount
@@ -169,21 +186,31 @@ public interface Inventory extends Iterable<ItemStack> {
      * Find all slots in the inventory containing any ItemStacks with the given materialId.
      *
      * @param materialId The materialId to look for
-     * @return The Slots found.
+     * @return A HashMap containing the slot index, ItemStack pairs
      */
     public HashMap<Integer, ? extends ItemStack> all(int materialId);
 
     /**
-     * Find all slots in the inventory containing any ItemStacks with the given material.
+     * Returns a HashMap with all slots and ItemStacks in the inventory with
+     * the given Material.
+     * <p />
+     * The HashMap contains entries where, the key is the slot index, and the
+     * value is the ItemStack in that slot. If no matching ItemStack with the
+     * given Material is found, an empty map is returned.
      *
      * @param material The material to look for
-     * @return A map from slot indexes to item at index
+     * @return A HashMap containing the slot index, ItemStack pairs
      * @throws IllegalArgumentException if material is null
      */
     public HashMap<Integer, ? extends ItemStack> all(Material material) throws IllegalArgumentException;
 
     /**
-     * Find all slots in the inventory containing the exact ItemStack specified.
+     * Finds all slots in the inventory containing any ItemStacks with the given ItemStack
+     * This will only match slots if both the type and the amount of the stack match
+     * <p />
+     * The HashMap contains entries where, the key is the
+     * slot index, and the value is the ItemStack in that slot. If no matching
+     * ImemStrack with the given Material is found, an empty map is returned.
      *
      * @param item The ItemStack to match against
      * @return A map from slot indexes to item at index
@@ -191,47 +218,47 @@ public interface Inventory extends Iterable<ItemStack> {
     public HashMap<Integer, ? extends ItemStack> all(ItemStack item);
 
     /**
-     * Find the first slot in the inventory containing an ItemStack with the given materialId.
+     * Finds the first slot in the inventory containing an ItemStack with the given materialId.
      *
      * @param materialId The materialId to look for
-     * @return The Slot found.
+     * @return The slot index of the given materialId or -1 if not found
      */
     public int first(int materialId);
 
     /**
-     * Find the first slot in the inventory containing an ItemStack with the given material
+     * Finds the first slot in the inventory containing an ItemStack with the given material
      *
      * @param material The material to look for
-     * @return The Slot found.
+     * @return The slot index of the given Material or -1 if not found
      * @throws IllegalArgumentException if material is null
      */
     public int first(Material material) throws IllegalArgumentException;
 
     /**
-     * Find the first slot in the inventory containing an ItemStack with the given stack
+     * Returns the first slot in the inventory containing an ItemStack with the given stack
      * This will only match a slot if both the type and the amount of the stack match
      *
      * @param item The ItemStack to match against
-     * @return The Slot found.
+     * @return The slot index of the given ItemStack or -1 if not found
      */
     public int first(ItemStack item);
 
     /**
-     * Find the first empty Slot.
+     * Returns the first empty Slot.
      *
      * @return The first empty Slot found, or -1 if no empty slots.
      */
     public int firstEmpty();
 
     /**
-     * Remove all stacks in the inventory matching the given materialId.
+     * Removes all stacks in the inventory matching the given materialId.
      *
      * @param materialId The material to remove
      */
     public void remove(int materialId);
 
     /**
-     * Remove all stacks in the inventory matching the given material.
+     * Removes all stacks in the inventory matching the given material.
      *
      * @param material The material to remove
      * @throws IllegalArgumentException if material is null
@@ -239,7 +266,7 @@ public interface Inventory extends Iterable<ItemStack> {
     public void remove(Material material) throws IllegalArgumentException;
 
     /**
-     * Remove all stacks in the inventory matching the given stack.
+     * Removes all stacks in the inventory matching the given stack.
      * This will only match a slot if both the type and the amount of the stack match
      *
      * @param item The ItemStack to match against
@@ -247,41 +274,45 @@ public interface Inventory extends Iterable<ItemStack> {
     public void remove(ItemStack item);
 
     /**
-     * Clear out a particular slot in the index
+     * Clears out a particular slot in the index.
      *
      * @param index The index to empty.
      */
     public void clear(int index);
 
     /**
-     * Clear out the whole index
+     * Clears out the whole Inventory.
      */
     public void clear();
 
     /**
-     * Get a list of players viewing. Note that a player is considered to be viewing their own
+     * Gets a list of players viewing. Note that a player is considered to be viewing their own
      * inventory and internal crafting screen even when said inventory is not open. They will normally
      * be considered to be viewing their inventory even when they have a different inventory screen open,
      * but it's possible for customized inventory screens to exclude the viewer's inventory, so this should
      * never be assumed to be non-empty.
-     * @return A list of players.
+     *
+     * @return A list of HumanEntities who are viewing this Inventory.
      */
     public List<HumanEntity> getViewers();
 
     /**
-     * Get the title of this inventory.
+     * Returns the title of this inventory.
-     * @return The title.
+     *
+     * @return A String with the title.
      */
     public String getTitle();
 
     /**
-     * Check what type of inventory this is.
+     * Returns what type of inventory this is.
-     * @return The type of inventory.
+     *
+     * @return The InventoryType representing the type of inventory.
      */
     public InventoryType getType();
 
     /**
      * Gets the block or entity belonging to the open inventory
+     *
      * @return The holder of the inventory; null if it has no holder.
      */
     public InventoryHolder getHolder();
@@ -292,6 +323,7 @@ public interface Inventory extends Iterable<ItemStack> {
      * Returns an iterator starting at the given index. If the index is positive, then the first
      * call to next() will return the item at that index; if it is negative, the first call to
      * previous will return the item at index (getSize() + index).
+     *
      * @param index The index.
      * @return An iterator.
      */

src/main/java/org/bukkit/inventory/InventoryView.java

@@ -14,7 +14,7 @@ import org.bukkit.event.inventory.InventoryType;
 public abstract class InventoryView {
     public final static int OUTSIDE = -999;
     /**
-     * Represents various extra properties of certai inventory windows.
+     * Represents various extra properties of certain inventory windows.
      */
     public enum Property {
         /**
@@ -107,7 +107,7 @@ public abstract class InventoryView {
     }
 
     /**
-     * Sets one item in this inventory view by its raw slot ID.
+     * Gets one item in this inventory view by its raw slot ID.
      * @param slot The ID as returned by InventoryClickEvent.getRawSlot()
      * @return The item currently in the slot.
      */

src/main/java/org/bukkit/inventory/ShapedRecipe.java

@@ -32,7 +32,9 @@ public class ShapedRecipe implements Recipe {
 
     /**
      * Set the shape of this recipe to the specified rows. Each character represents a different
-     * ingredient; exactly what each character represents is set separately.
+     * ingredient; exactly what each character represents is set separately. The first row supplied
+     * corresponds with the upper most part of the recipe on the workbench e.g. if all three 
+     * rows are supplies the first string represents the top row on the workbench.
      *
      * @param shape The rows of the recipe (up to 3 rows).
      * @return The changed recipe, so you can chain calls.

src/main/java/org/bukkit/inventory/meta/BookMeta.java

@@ -18,13 +18,14 @@ public interface BookMeta extends ItemMeta {
 
     /**
      * Gets the title of the book.
+     * Plugins should check that hasTitle() returns true before calling this method.
      *
      * @return the title of the book
      */
     String getTitle();
 
     /**
-     * Sets the title of the book. Limited to 16 characters.
+     * Sets the title of the book. Limited to 16 characters. Removes title when given null.
      *
      * @param title the title to set
      * @return true if the title was successfully set
@@ -40,13 +41,14 @@ public interface BookMeta extends ItemMeta {
 
     /**
      * Gets the author of the book.
+     * Plugins should check that hasAuthor() returns true before calling this method.
      *
      * @return the author of the book
      */
     String getAuthor();
 
     /**
-     * Sets the author of the book.
+     * Sets the author of the book. Removes author when given null.
      *
      * @param author the author of the book
      */
@@ -60,7 +62,7 @@ public interface BookMeta extends ItemMeta {
     boolean hasPages();
 
     /**
-     * Gets the specified page in the book.
+     * Gets the specified page in the book. The given page must exist.
      *
      * @param page the page number to get
      * @return the page from the book
@@ -68,7 +70,8 @@ public interface BookMeta extends ItemMeta {
     String getPage(int page);
 
     /**
-     * Sets the specified page in the book.
+     * Sets the specified page in the book. Pages of the book must be contiguous.
+     * The data can be up to 256 characters in length, additional characters are trucated.
      *
      * @param page the page number to set
      * @param data the data to set for that page
@@ -97,7 +100,7 @@ public interface BookMeta extends ItemMeta {
     void setPages(String... pages);
 
     /**
-     * Adds new pages to the end of the book.
+     * Adds new pages to the end of the book. Up to a maximum of 50 pages with 256 characters per page.
      *
      * @param pages A list of strings, each being a page
      */

src/main/java/org/bukkit/inventory/meta/ItemMeta.java

@@ -14,56 +14,59 @@ import org.bukkit.enchantments.Enchantment;
 public interface ItemMeta extends Cloneable, ConfigurationSerializable {
 
     /**
-     * Checks for existence of a display name
+     * Checks for existence of a display name.
      *
      * @return true if this has a display name
      */
     boolean hasDisplayName();
 
     /**
-     * Gets the display name that is set
+     * Gets the display name that is set.
+     * Plugins should check that hasDisplayName() returns <code>true</code> before calling this method.
      *
      * @return the display name that is set
      */
     String getDisplayName();
 
     /**
-     * Sets the display name
+     * Sets the display name.
      *
      * @param name the name to set
      */
     void setDisplayName(String name);
 
     /**
-     * Checks for existence of lore
+     * Checks for existence of lore.
      *
      * @return true if this has lore
      */
     boolean hasLore();
 
     /**
-     * Gets the lore that is set
+     * Gets the lore that is set.
+     * Plugins should check if hasLore() returns <code>true</code> before calling this method.
      * 
      * @return a list of lore that is set
      */
     List<String> getLore();
 
     /**
-     * Sets the lore for this item
+     * Sets the lore for this item. 
+     * Removes lore when given null.
      *
      * @param lore the lore that will be set
      */
     void setLore(List<String> lore);
 
     /**
-     * Checks for the existence of any enchantments
+     * Checks for the existence of any enchantments.
      *
      * @return true if an enchantment exists on this meta
      */
     boolean hasEnchants();
 
     /**
-     * Checks for existence of the specified enchantment
+     * Checks for existence of the specified enchantment.
      *
      * @param ench enchantment to check
      * @return true if this enchantment exists for this meta
@@ -71,7 +74,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable {
     boolean hasEnchant(Enchantment ench);
 
     /**
-     * Checks for the level of the specified enchantment
+     * Checks for the level of the specified enchantment.
      *
      * @param ench enchantment to check
      * @return The level that the specified enchantment has, or 0 if none
@@ -79,14 +82,15 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable {
     int getEnchantLevel(Enchantment ench);
 
     /**
-     * This method gets a copy the enchantments in this ItemMeta
+     * Returns a copy the enchantments in this ItemMeta.<br />
+     * Returns an empty map if none.
      *
      * @return An immutable copy of the enchantments
      */
     Map<Enchantment, Integer> getEnchants();
 
     /**
-     * This method adds the specified enchantment to this item meta
+     * Adds the specified enchantment to this item meta.
      *
      * @param ench Enchantment to add
      * @param level Level for the enchantment
@@ -96,7 +100,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable {
     boolean addEnchant(Enchantment ench, int level, boolean ignoreLevelRestriction);
 
     /**
-     * This method removes the specified enchantment from this item meta
+     * Removes the specified enchantment from this item meta.
      *
      * @param ench Enchantment to remove
      * @return true if the item meta changed as a result of this call, false otherwise

src/main/java/org/bukkit/inventory/meta/MapMeta.java

@@ -6,14 +6,14 @@ package org.bukkit.inventory.meta;
 public interface MapMeta extends ItemMeta {
 
     /**
-     * Checks to see if this map is scaling
+     * Checks to see if this map is scaling.
      *
      * @return true if this map is scaling
      */
     boolean isScaling();
 
     /**
-     * Sets if this map is scaling or not
+     * Sets if this map is scaling or not.
      *
      * @param value true to scale
      */

src/main/java/org/bukkit/inventory/meta/PotionMeta.java

@@ -12,21 +12,22 @@ import java.util.List;
 public interface PotionMeta extends ItemMeta {
 
     /**
-     * Checks for the presence of custom potion effects
+     * Checks for the presence of custom potion effects.
      *
      * @return true if custom potion effects are applied
      */
     boolean hasCustomEffects();
 
     /**
-     * Gets an immutable list containing all custom potion effects applied to this potion
+     * Gets an immutable list containing all custom potion effects applied to this potion.
+     * Plugins should check that hasCustomEffects() returns true before calling this method.
      *
      * @return the immutable list of custom potion effects
      */
     List<PotionEffect> getCustomEffects();
 
     /**
-     * Adds a custom potion effect to this potion
+     * Adds a custom potion effect to this potion.
      *
      * @param effect the potion effect to add
      * @param overwrite true if any existing effect of the same type should be overwritten
@@ -35,7 +36,7 @@ public interface PotionMeta extends ItemMeta {
     boolean addCustomEffect(PotionEffect effect, boolean overwrite);
 
     /**
-     * Removes a custom potion effect from this potion
+     * Removes a custom potion effect from this potion.
      *
      * @param type the potion effect type to remove
      * @return true if the potion meta changed as a result of this call
@@ -43,7 +44,8 @@ public interface PotionMeta extends ItemMeta {
     boolean removeCustomEffect(PotionEffectType type);
 
     /**
-     * Checks for a specific custom potion effect type on this potion
+     * Checks for a specific custom potion effect type on this potion.
+     * 
      * @param type the potion effect type to check for
      * @return true if the potion has this effect
      */
@@ -59,7 +61,7 @@ public interface PotionMeta extends ItemMeta {
     boolean setMainEffect(PotionEffectType type);
 
     /**
-     * Removes all custom potion effects from this potion
+     * Removes all custom potion effects from this potion.
      *
      * @return true if the potion meta changed as a result of this call
      */

src/main/java/org/bukkit/inventory/meta/SkullMeta.java

@@ -8,21 +8,22 @@ import org.bukkit.Material;
 public interface SkullMeta extends ItemMeta {
 
     /**
-     * Gets the owner of the skull
+     * Gets the owner of the skull.
      *
      * @return the owner if the skull
      */
     String getOwner();
 
     /**
-     * Checks to see if the skull has an owner
+     * Checks to see if the skull has an owner.
      *
      * @return true if the skull has an owner
      */
     boolean hasOwner();
 
     /**
-     * Sets the owner of the skull
+     * Sets the owner of the skull.
+     * Plugins should check that hasOwner() returns true before calling this plugin.
      *
      * @param owner the new owner of the skull
      * @return true if the owner was successfully set

src/main/java/org/bukkit/material/Crops.java

@@ -35,7 +35,7 @@ public class Crops extends MaterialData {
     /**
      * Gets the current growth state of this crop
      *
-     * @return CropState of this leave
+     * @return CropState of this crop
      */
     public CropState getState() {
         return CropState.getByData(getData());

src/main/java/org/bukkit/scheduler/BukkitRunnable.java

@@ -10,7 +10,8 @@ public abstract class BukkitRunnable implements Runnable {
     private int taskId = -1;
 
     /**
-     * Attempts to cancel this task
+     * Attempts to cancel this task.
+     *
      * @throws IllegalStateException if task was not scheduled yet
      */
     public synchronized void cancel() throws IllegalStateException {
@@ -18,7 +19,7 @@ public abstract class BukkitRunnable implements Runnable {
     }
 
     /**
-     * Schedules this in the Bukkit scheduler to run on next tick
+     * Schedules this in the Bukkit scheduler to run on next tick.
      *
      * @param plugin the reference to the plugin scheduling task
      * @return a BukkitTask that contains the id number
@@ -83,7 +84,7 @@ public abstract class BukkitRunnable implements Runnable {
     }
 
     /**
-     * Schedules this to repeatedly run until cancelled, starting after the specified number of server ticks
+     * Schedules this to repeatedly run until cancelled, starting after the specified number of server ticks.
      *
      * @param plugin the reference to the plugin scheduling task
      * @param delay the ticks to wait before running the task
@@ -118,7 +119,8 @@ public abstract class BukkitRunnable implements Runnable {
     }
 
     /**
-     * Gets the task id for this runnable
+     * Gets the task id for this runnable.
+     *
      * @return the task id that this runnable was scheduled as
      * @throws IllegalStateException if task was not scheduled yet
      */

src/main/java/org/bukkit/scheduler/BukkitScheduler.java

@@ -8,8 +8,8 @@ import java.util.List;
 public interface BukkitScheduler {
 
     /**
-     * Schedules a once off task to occur after a delay
+     * Schedules a once off task to occur after a delay.
-     * This task will be executed by the main server thread
+     * This task will be executed by the main server thread.
      *
      * @param plugin Plugin that owns the task
      * @param task Task to be executed
@@ -19,8 +19,8 @@ public interface BukkitScheduler {
     public int scheduleSyncDelayedTask(Plugin plugin, Runnable task, long delay);
 
     /**
-     * Schedules a once off task to occur as soon as possible
+     * Schedules a once off task to occur as soon as possible.
-     * This task will be executed by the main server thread
+     * This task will be executed by the main server thread.
      *
      * @param plugin Plugin that owns the task
      * @param task Task to be executed
@@ -29,8 +29,8 @@ public interface BukkitScheduler {
     public int scheduleSyncDelayedTask(Plugin plugin, Runnable task);
 
     /**
-     * Schedules a repeating task
+     * Schedules a repeating task.
-     * This task will be executed by the main server thread
+     * This task will be executed by the main server thread.
      *
      * @param plugin Plugin that owns the task
      * @param task Task to be executed
@@ -44,8 +44,8 @@ public interface BukkitScheduler {
      * <b>Asynchronous tasks should never access any API in Bukkit.
      *    Great care should be taken to assure the thread-safety of asynchronous tasks.</b>
      * <br>
-     * <br>Schedules a once off task to occur after a delay,
+     * <br>Schedules a once off task to occur after a delay.
-     * This task will be executed by a thread managed by the scheduler
+     * This task will be executed by a thread managed by the scheduler.
      *
      * @param plugin Plugin that owns the task
      * @param task Task to be executed
@@ -61,7 +61,7 @@ public interface BukkitScheduler {
      *    Great care should be taken to assure the thread-safety of asynchronous tasks.</b>
      * <br>
      * <br>Schedules a once off task to occur as soon as possible.
-     * This task will be executed by a thread managed by the scheduler
+     * This task will be executed by a thread managed by the scheduler.
      *
      * @param plugin Plugin that owns the task
      * @param task Task to be executed
@@ -76,7 +76,7 @@ public interface BukkitScheduler {
      *    Great care should be taken to assure the thread-safety of asynchronous tasks.</b>
      * <br>
      * <br>Schedules a repeating task.
-     * This task will be executed by a thread managed by the scheduler
+     * This task will be executed by a thread managed by the scheduler.
      *
      * @param plugin Plugin that owns the task
      * @param task Task to be executed
@@ -90,10 +90,10 @@ public interface BukkitScheduler {
 
     /**
      * Calls a method on the main thread and returns a Future object
-     * This task will be executed by the main server thread
+     * This task will be executed by the main server thread.
      * <p />
-     * Note: The Future.get() methods must NOT be called from the main thread
+     * Note: The Future.get() methods must NOT be called from the main thread.
-     * Note2: There is at least an average of 10ms latency until the isDone() method returns true
+     * Note2: There is at least an average of 10ms latency until the isDone() method returns true.
      *
      * @param <T> The callable's return type
      * @param plugin Plugin that owns the task
@@ -103,21 +103,21 @@ public interface BukkitScheduler {
     public <T> Future<T> callSyncMethod(Plugin plugin, Callable<T> task);
 
     /**
-     * Removes task from scheduler
+     * Removes task from scheduler.
      *
      * @param taskId Id number of task to be removed
      */
     public void cancelTask(int taskId);
 
     /**
-     * Removes all tasks associated with a particular plugin from the scheduler
+     * Removes all tasks associated with a particular plugin from the scheduler.
      *
      * @param plugin Owner of tasks to be removed
      */
     public void cancelTasks(Plugin plugin);
 
     /**
-     * Removes all tasks from the scheduler
+     * Removes all tasks from the scheduler.
      */
     public void cancelAllTasks();
 
@@ -216,7 +216,7 @@ public interface BukkitScheduler {
     public BukkitTask runTaskLaterAsynchronously(Plugin plugin, Runnable task, long delay) throws IllegalArgumentException;
 
     /**
-     * Returns a task that will repeatedly run until cancelled, starting after the specified number of server ticks
+     * Returns a task that will repeatedly run until cancelled, starting after the specified number of server ticks.
      *
      * @param plugin the reference to the plugin scheduling task
      * @param task the task to be run

src/main/java/org/bukkit/scheduler/BukkitTask.java

@@ -9,28 +9,28 @@ import org.bukkit.plugin.Plugin;
 public interface BukkitTask {
 
     /**
-     * Returns the taskId for the task
+     * Returns the taskId for the task.
      *
      * @return Task id number
      */
     public int getTaskId();
 
     /**
-     * Returns the Plugin that owns this task
+     * Returns the Plugin that owns this task.
      *
      * @return The Plugin that owns the task
      */
     public Plugin getOwner();
 
     /**
-     * Returns true if the Task is a sync task
+     * Returns true if the Task is a sync task.
      *
      * @return true if the task is run by main thread
      */
     public boolean isSync();
 
     /**
-     * Will attempt to cancel this task
+     * Will attempt to cancel this task.
      */
     public void cancel();
 }

src/main/java/org/bukkit/scheduler/BukkitWorker.java

@@ -12,21 +12,21 @@ import org.bukkit.plugin.Plugin;
 public interface BukkitWorker {
 
     /**
-     * Returns the taskId for the task being executed by this worker
+     * Returns the taskId for the task being executed by this worker.
      *
      * @return Task id number
      */
     public int getTaskId();
 
     /**
-     * Returns the Plugin that owns this task
+     * Returns the Plugin that owns this task.
      *
      * @return The Plugin that owns the task
      */
     public Plugin getOwner();
 
     /**
-     * Returns the thread for the worker
+     * Returns the thread for the worker.
      *
      * @return The Thread object for the worker
      */