diff options
Diffstat (limited to 'src/main/java/org/bukkit/inventory/Inventory.java')
| -rw-r--r-- | src/main/java/org/bukkit/inventory/Inventory.java | 128 |
1 files changed, 80 insertions, 48 deletions
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. */ |