diff options
author | feildmaster <admin@feildmaster.com> | 2013-01-22 15:09:24 -0600 |
---|---|---|
committer | feildmaster <admin@feildmaster.com> | 2013-01-22 16:41:00 -0600 |
commit | 05c2c55fce91e4fa68d97f7acbd98145778624c4 (patch) | |
tree | a6ce054735109e2964e3c796146a88a841738ff7 | |
parent | 2f6cee111d0ba73e2561e77bb75e5ace5b382b9b (diff) | |
download | bukkit-05c2c55fce91e4fa68d97f7acbd98145778624c4.tar bukkit-05c2c55fce91e4fa68d97f7acbd98145778624c4.tar.gz bukkit-05c2c55fce91e4fa68d97f7acbd98145778624c4.tar.lz bukkit-05c2c55fce91e4fa68d97f7acbd98145778624c4.tar.xz bukkit-05c2c55fce91e4fa68d97f7acbd98145778624c4.zip |
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.
26 files changed, 253 insertions, 144 deletions
diff --git a/src/main/java/org/bukkit/ChatColor.java b/src/main/java/org/bukkit/ChatColor.java index fcaa04ef..6082c624 100644 --- a/src/main/java/org/bukkit/ChatColor.java +++ b/src/main/java/org/bukkit/ChatColor.java @@ -193,10 +193,10 @@ 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. + * @param textToTranslate Text containing the alternate color code character. * @return Text containing the ChatColor.COLOR_CODE color code character. */ public static String translateAlternateColorCodes(char altColorChar, String textToTranslate) { diff --git a/src/main/java/org/bukkit/Color.java b/src/main/java/org/bukkit/Color.java index e5ddc422..b544af20 100644 --- a/src/main/java/org/bukkit/Color.java +++ b/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(blue >= 0 && blue <= BIT_MASK, "Red is not between 0-255: ", blue); + Validate.isTrue(green >= 0 && green <= BIT_MASK, "Green is not between 0-255: ", green); + Validate.isTrue(blue >= 0 && blue <= BIT_MASK, "Blue is not between 0-255: ", blue); this.red = (byte) red; this.green = (byte) green; diff --git a/src/main/java/org/bukkit/Server.java b/src/main/java/org/bukkit/Server.java index ceec40cc..49c3f5c3 100644 --- a/src/main/java/org/bukkit/Server.java +++ b/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(); diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java index a608525d..4b9e39e2 100644 --- a/src/main/java/org/bukkit/World.java +++ b/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(); diff --git a/src/main/java/org/bukkit/command/defaults/TeleportCommand.java b/src/main/java/org/bukkit/command/defaults/TeleportCommand.java index 2a18efe5..2147d3ee 100644 --- a/src/main/java/org/bukkit/command/defaults/TeleportCommand.java +++ b/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.usageMessage = "/tp [player] <target>\n/tp [player] <x> <y> <z>"; + this.description = "Teleports the given player (or yourself) to another player or coordinates"; + this.usageMessage = "/tp [player] <target> and/or <x> <y> <z>"; this.setPermission("bukkit.command.teleport"); } diff --git a/src/main/java/org/bukkit/command/defaults/WhitelistCommand.java b/src/main/java/org/bukkit/command/defaults/WhitelistCommand.java index 04a24c5e..b3fa4f82 100644 --- a/src/main/java/org/bukkit/command/defaults/WhitelistCommand.java +++ b/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"); } diff --git a/src/main/java/org/bukkit/configuration/ConfigurationSection.java b/src/main/java/org/bukkit/configuration/ConfigurationSection.java index 60b53524..9a11fd34 100644 --- a/src/main/java/org/bukkit/configuration/ConfigurationSection.java +++ b/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. diff --git a/src/main/java/org/bukkit/entity/Entity.java b/src/main/java/org/bukkit/entity/Entity.java index a9df5c5c..771316d8 100644 --- a/src/main/java/org/bukkit/entity/Entity.java +++ b/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(); diff --git a/src/main/java/org/bukkit/entity/EntityType.java b/src/main/java/org/bukkit/entity/EntityType.java index 99a5556a..b83a0703 100644 --- a/src/main/java/org/bukkit/entity/EntityType.java +++ b/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 diff --git a/src/main/java/org/bukkit/event/block/BlockIgniteEvent.java b/src/main/java/org/bukkit/event/block/BlockIgniteEvent.java index 65b943fd..2ff8fc4a 100644 --- a/src/main/java/org/bukkit/event/block/BlockIgniteEvent.java +++ b/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, } diff --git a/src/main/java/org/bukkit/event/player/PlayerFishEvent.java b/src/main/java/org/bukkit/event/player/PlayerFishEvent.java index a41c62b2..e675b5c7 100644 --- a/src/main/java/org/bukkit/event/player/PlayerFishEvent.java +++ b/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, /** diff --git a/src/main/java/org/bukkit/event/server/ServerListPingEvent.java b/src/main/java/org/bukkit/event/server/ServerListPingEvent.java index ddbdaeee..d8369bce 100644 --- a/src/main/java/org/bukkit/event/server/ServerListPingEvent.java +++ b/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; diff --git a/src/main/java/org/bukkit/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java index 4311d3d3..d3e736cc 100644 --- a/src/main/java/org/bukkit/inventory/EntityEquipment.java +++ b/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(); } diff --git a/src/main/java/org/bukkit/inventory/Inventory.java b/src/main/java/org/bukkit/inventory/Inventory.java index 35c45673..0f7fab92 100644 --- a/src/main/java/org/bukkit/inventory/Inventory.java +++ b/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. - * It will return a HashMap of what it couldn't fit. + * This will try to fill existing stacks and empty slots as well as it can. + * <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. - * This will only match if both the type and the amount of the stack match. + * Checks if the inventory contains any ItemStacks matching the given ItemStack. + * 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. - * This ignores the size of the stack, using the {@link ItemStack#isSimilar(ItemStack)} method. + * Returns a HashMap with all slots and ItemStacks in the inventory with + * 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. - * @return The title. + * Returns the title of this inventory. + * + * @return A String with the title. */ public String getTitle(); /** - * Check what type of inventory this is. - * @return The type of inventory. + * Returns what type of inventory this is. + * + * @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. */ diff --git a/src/main/java/org/bukkit/inventory/InventoryView.java b/src/main/java/org/bukkit/inventory/InventoryView.java index d8c4f1e7..4e0d4947 100644 --- a/src/main/java/org/bukkit/inventory/InventoryView.java +++ b/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. */ diff --git a/src/main/java/org/bukkit/inventory/ShapedRecipe.java b/src/main/java/org/bukkit/inventory/ShapedRecipe.java index 577597ce..4d057ae0 100644 --- a/src/main/java/org/bukkit/inventory/ShapedRecipe.java +++ b/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. diff --git a/src/main/java/org/bukkit/inventory/meta/BookMeta.java b/src/main/java/org/bukkit/inventory/meta/BookMeta.java index 987a2866..73148397 100644 --- a/src/main/java/org/bukkit/inventory/meta/BookMeta.java +++ b/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 */ diff --git a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java index fe744546..3b0c1559 100644 --- a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java +++ b/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 diff --git a/src/main/java/org/bukkit/inventory/meta/MapMeta.java b/src/main/java/org/bukkit/inventory/meta/MapMeta.java index 6ff13671..fb5c2970 100644 --- a/src/main/java/org/bukkit/inventory/meta/MapMeta.java +++ b/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 */ diff --git a/src/main/java/org/bukkit/inventory/meta/PotionMeta.java b/src/main/java/org/bukkit/inventory/meta/PotionMeta.java index dad8fc30..de7d5e82 100644 --- a/src/main/java/org/bukkit/inventory/meta/PotionMeta.java +++ b/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 */ diff --git a/src/main/java/org/bukkit/inventory/meta/SkullMeta.java b/src/main/java/org/bukkit/inventory/meta/SkullMeta.java index 42598576..f8aab18d 100644 --- a/src/main/java/org/bukkit/inventory/meta/SkullMeta.java +++ b/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 diff --git a/src/main/java/org/bukkit/material/Crops.java b/src/main/java/org/bukkit/material/Crops.java index 04f8ddf2..c874d5fb 100644 --- a/src/main/java/org/bukkit/material/Crops.java +++ b/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()); diff --git a/src/main/java/org/bukkit/scheduler/BukkitRunnable.java b/src/main/java/org/bukkit/scheduler/BukkitRunnable.java index 15e0d688..f51f5236 100644 --- a/src/main/java/org/bukkit/scheduler/BukkitRunnable.java +++ b/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 */ diff --git a/src/main/java/org/bukkit/scheduler/BukkitScheduler.java b/src/main/java/org/bukkit/scheduler/BukkitScheduler.java index 012e777e..5cc9196b 100644 --- a/src/main/java/org/bukkit/scheduler/BukkitScheduler.java +++ b/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 - * This task will be executed by the main server thread + * Schedules a once off task to occur after a delay. + * 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 - * This task will be executed by the main server thread + * Schedules a once off task to occur as soon as possible. + * 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 - * This task will be executed by the main server thread + * Schedules a repeating task. + * 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, - * This task will be executed by a thread managed by the scheduler + * <br>Schedules a once off task to occur after a delay. + * 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 - * Note2: There is at least an average of 10ms latency until the isDone() method returns true + * 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. * * @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 diff --git a/src/main/java/org/bukkit/scheduler/BukkitTask.java b/src/main/java/org/bukkit/scheduler/BukkitTask.java index 17ea1fae..890c7315 100644 --- a/src/main/java/org/bukkit/scheduler/BukkitTask.java +++ b/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(); } diff --git a/src/main/java/org/bukkit/scheduler/BukkitWorker.java b/src/main/java/org/bukkit/scheduler/BukkitWorker.java index 70a637b8..a889e893 100644 --- a/src/main/java/org/bukkit/scheduler/BukkitWorker.java +++ b/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 */ |