OpenSource/PaperMC
OpenSource/PaperMC
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2025-01-24 01:06:01 +01:00
Code Issues Projects Releases Packages 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
Show stats Download patch file Download diff file Expand all files Collapse all files

6
paper-api/src/main/java/org/bukkit/ChatColor.java
View file

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

4
paper-api/src/main/java/org/bukkit/Color.java
View file

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

8
paper-api/src/main/java/org/bukkit/Server.java
View file

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

6
paper-api/src/main/java/org/bukkit/World.java
View file

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

4
paper-api/src/main/java/org/bukkit/command/defaults/TeleportCommand.java
View file

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

2
paper-api/src/main/java/org/bukkit/command/defaults/WhitelistCommand.java
View file

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

20
paper-api/src/main/java/org/bukkit/configuration/ConfigurationSection.java
View file

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

2
paper-api/src/main/java/org/bukkit/entity/Entity.java
View file

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

67
paper-api/src/main/java/org/bukkit/entity/EntityType.java
View file

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

2
paper-api/src/main/java/org/bukkit/event/block/BlockIgniteEvent.java
View file

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

6
paper-api/src/main/java/org/bukkit/event/player/PlayerFishEvent.java
View file

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

2
paper-api/src/main/java/org/bukkit/event/server/ServerListPingEvent.java
View file

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

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

2
paper-api/src/main/java/org/bukkit/material/Crops.java
View file

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

10
paper-api/src/main/java/org/bukkit/scheduler/BukkitRunnable.java
View file

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

34
paper-api/src/main/java/org/bukkit/scheduler/BukkitScheduler.java
View file

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

8
paper-api/src/main/java/org/bukkit/scheduler/BukkitTask.java
View file

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

6
paper-api/src/main/java/org/bukkit/scheduler/BukkitWorker.java
View file

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