SteamWar/Paper
9
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve javadoc in 26 files.

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

By: feildmaster <admin@feildmaster.com>
This commit is contained in:
Bukkit/Spigot
2013-01-22 15:09:24 -06:00
parent c5392313d3
commit 8065c9095a
26 changed files with 253 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
paper-api/src/main/java/org/bukkit/inventory/EntityEquipment.java
View File

@@ -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();
}

128
paper-api/src/main/java/org/bukkit/inventory/Inventory.java
View File

@@ -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.
*/

4
paper-api/src/main/java/org/bukkit/inventory/InventoryView.java
View File

@@ -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.
*/

4
paper-api/src/main/java/org/bukkit/inventory/ShapedRecipe.java
View File

@@ -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.

13
paper-api/src/main/java/org/bukkit/inventory/meta/BookMeta.java
View File

@@ -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
*/

30
paper-api/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
View File

@@ -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

4
paper-api/src/main/java/org/bukkit/inventory/meta/MapMeta.java
View File

@@ -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
*/

14
paper-api/src/main/java/org/bukkit/inventory/meta/PotionMeta.java
View File

@@ -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
*/

7
paper-api/src/main/java/org/bukkit/inventory/meta/SkullMeta.java
View File

@@ -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