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

Fix upstream javadocs

Browse Source
This commit is contained in:
Zach Brown
2017-06-10 16:59:40 -05:00
parent f7eff332be
commit 0c37d20354
75 changed files with 403 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -37,9 +37,23 @@ public interface EntityEquipment {
public ItemStack getItem(@NotNull EquipmentSlot slot);
/**
* Gets a copy of the item the entity is currently holding
* Gets the item the entity is currently holding
* in their main hand.
*
* <p>
* This returns a copy if this equipment instance is from a non-player,
* or it's an empty stack (has AIR as its type).
* For non-empty stacks from players, this returns a live mirror. You can check if this
* will return a mirror with
* <pre>{@code
* EntityEquipment equipment = entity.getEquipment();
* if (equipment instanceof PlayerInventory) {
* equipment.getItemInMainHand(); // will return a mirror
* } else {
* equipment.getItemInMainHand(); // will return a copy
* }
* }</pre>
*
* @return the currently held item
*/
@NotNull
@@ -61,9 +75,23 @@ public interface EntityEquipment {
void setItemInMainHand(@Nullable ItemStack item, boolean silent);
/**
* Gets a copy of the item the entity is currently holding
* Gets the item the entity is currently holding
* in their off hand.
*
* <p>
* This returns a copy if this equipment instance is from a non-player,
* or it's an empty stack (has AIR as its type).
* For non-empty stacks from players, this returns a live mirror. You can check if this
* will return a mirror with
* <pre>{@code
* EntityEquipment equipment = entity.getEquipment();
* if (equipment instanceof PlayerInventory) {
* equipment.getItemInOffHand(); // will return a mirror
* } else {
* equipment.getItemInOffHand(); // will return a copy
* }
* }</pre>
*
* @return the currently held item
*/
@NotNull
@@ -85,7 +113,21 @@ public interface EntityEquipment {
void setItemInOffHand(@Nullable ItemStack item, boolean silent);
/**
* Gets a copy of the item the entity is currently holding
* Gets the item the entity is currently holding
*
* <p>
* This returns a copy if this equipment instance is from a non-player,
* or it's an empty stack (has AIR as its type).
* For non-empty stacks from players, this returns a live mirror. You can check if this
* will return a mirror with
* <pre>{@code
* EntityEquipment equipment = entity.getEquipment();
* if (equipment instanceof PlayerInventory) {
* equipment.getItemInHand(); // will return a mirror
* } else {
* equipment.getItemInHand(); // will return a copy
* }
* }</pre>
*
* @return the currently held item
* @see #getItemInMainHand()
@@ -110,11 +152,24 @@ public interface EntityEquipment {
void setItemInHand(@Nullable ItemStack stack);
/**
* Gets a copy of the helmet currently being worn by the entity
* Gets the helmet currently being worn by the entity
*
* <p>
* This returns a copy if this equipment instance is from a non-player.
* For stacks from players, this returns a live mirror (or null). You can check if this
* will return a mirror with
* <pre>{@code
* EntityEquipment equipment = entity.getEquipment();
* if (equipment instanceof PlayerInventory) {
* equipment.getHelmet(); // will return a mirror
* } else {
* equipment.getHelmet(); // will return a copy
* }
* }</pre>
*
* @return The helmet being worn
*/
@Nullable
@org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
ItemStack getHelmet();
/**
@@ -133,11 +188,24 @@ public interface EntityEquipment {
void setHelmet(@Nullable ItemStack helmet, boolean silent);
/**
* Gets a copy of the chest plate currently being worn by the entity
* Gets the chest plate currently being worn by the entity
*
* <p>
* This returns a copy if this equipment instance is from a non-player.
* For stacks from players, this returns a live mirror (or null). You can check if this
* will return a mirror with
* <pre>{@code
* EntityEquipment equipment = entity.getEquipment();
* if (equipment instanceof PlayerInventory) {
* equipment.getChestplate(); // will return a mirror
* } else {
* equipment.getChestplate(); // will return a copy
* }
* }</pre>
*
* @return The chest plate being worn
*/
@Nullable
@org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
ItemStack getChestplate();
/**
@@ -156,11 +224,24 @@ public interface EntityEquipment {
void setChestplate(@Nullable ItemStack chestplate, boolean silent);
/**
* Gets a copy of the leggings currently being worn by the entity
* Gets the leggings currently being worn by the entity
*
* <p>
* This returns a copy if this equipment instance is from a non-player.
* For stacks from players, this returns a live mirror (or null). You can check if this
* will return a mirror with
* <pre>{@code
* EntityEquipment equipment = entity.getEquipment();
* if (equipment instanceof PlayerInventory) {
* equipment.getLeggings(); // will return a mirror
* } else {
* equipment.getLeggings(); // will return a copy
* }
* }</pre>
*
* @return The leggings being worn
*/
@Nullable
@org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
ItemStack getLeggings();
/**
@@ -179,11 +260,24 @@ public interface EntityEquipment {
void setLeggings(@Nullable ItemStack leggings, boolean silent);
/**
* Gets a copy of the boots currently being worn by the entity
* Gets the boots currently being worn by the entity
*
* <p>
* This returns a copy if this equipment instance is from a non-player.
* For stacks from players, this returns a live mirror (or null). You can check if this
* will return a mirror with
* <pre>{@code
* EntityEquipment equipment = entity.getEquipment();
* if (equipment instanceof PlayerInventory) {
* equipment.getBoots(); // will return a mirror
* } else {
* equipment.getBoots(); // will return a copy
* }
* }</pre>
*
* @return The boots being worn
*/
@Nullable
@org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
ItemStack getBoots();
/**
@@ -204,12 +298,25 @@ public interface EntityEquipment {
/**
* Gets all ItemStacks from the armor slots.
*
* <p>
* This returns a copy if this equipment instance is from a non-player,
* or it's an empty stack (has AIR as its type).
* For non-empty stacks from players, this returns a live mirror. You can check if this
* will return a mirror with
* <pre>{@code
* EntityEquipment equipment = entity.getEquipment();
* if (equipment instanceof PlayerInventory) {
* equipment.getArmorContents(); // will return an array of mirror
* } else {
* equipment.getArmorContents(); // will return an array of copies
* }
* }</pre>
*
* @return all the ItemStacks from the armor slots. Individual items can be
* null and are returned in a fixed order starting from the boots and going
* up to the helmet
*/
@NotNull
ItemStack[] getArmorContents();
@org.bukkit.UndefinedNullability("not null elements for entities, nullable elements for players") ItemStack @NotNull [] getArmorContents(); // Paper
/**
* Sets the entities armor to the provided array of ItemStacks
@@ -249,7 +356,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop killed by anything
* </ul>
*
* @return chance of the currently held item being dropped (1 for non-{@link Mob})
@@ -262,7 +370,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance the chance of the main hand item being dropped
@@ -276,7 +385,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @return chance of the off hand item being dropped (1 for non-{@link Mob})
@@ -289,7 +399,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance the chance of off hand item being dropped
@@ -302,7 +413,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @return the chance of the helmet being dropped (1 for non-{@link Mob})
@@ -314,7 +426,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance of the helmet being dropped
@@ -328,7 +441,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @return the chance of the chest plate being dropped (1 for non-{@link Mob})
@@ -341,7 +455,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance of the chest plate being dropped
@@ -355,7 +470,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @return the chance of the leggings being dropped (1 for non-{@link Mob})
@@ -368,7 +484,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance chance of the leggings being dropped
@@ -381,7 +498,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @return the chance of the boots being dropped (1 for non-{@link Mob})
@@ -393,7 +511,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
* <li>A drop chance of 1.0F will always drop
* <li>A drop chance of exactly 1.0F will always drop if killed by a player
* <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance of the boots being dropped

2
paper-api/src/main/java/org/bukkit/inventory/ItemFlag.java
View File

@@ -35,7 +35,7 @@ public enum ItemFlag {
*/
HIDE_DYE,
/**
* Setting to show/hide armor trim from leather armor.
* Setting to show/hide armor trim from armor.
*/
HIDE_ARMOR_TRIM;
}

6
paper-api/src/main/java/org/bukkit/inventory/PlayerInventory.java
View File

@@ -160,7 +160,7 @@ public interface PlayerInventory extends Inventory {
public void setBoots(@Nullable ItemStack boots);
/**
* Gets a copy of the item the player is currently holding
* Gets the item the player is currently holding
* in their main hand.
*
* @return the currently held item
@@ -176,7 +176,7 @@ public interface PlayerInventory extends Inventory {
void setItemInMainHand(@Nullable ItemStack item);
/**
* Gets a copy of the item the player is currently holding
* Gets the item the player is currently holding
* in their off hand.
*
* @return the currently held item
@@ -192,7 +192,7 @@ public interface PlayerInventory extends Inventory {
void setItemInOffHand(@Nullable ItemStack item);
/**
* Gets a copy of the item the player is currently holding
* Gets the item the player is currently holding
*
* @return the currently held item
* @see #getItemInMainHand()

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

@@ -24,8 +24,6 @@ public class ShapedRecipe extends CraftingRecipe {
* @param result The item you want the recipe to create.
* @see ShapedRecipe#shape(String...)
* @see ShapedRecipe#setIngredient(char, Material)
* @see ShapedRecipe#setIngredient(char, Material, int)
* @see ShapedRecipe#setIngredient(char, MaterialData)
* @see ShapedRecipe#setIngredient(char, RecipeChoice)
* @deprecated Recipes must have keys. Use {@link #ShapedRecipe(NamespacedKey, ItemStack)}
* instead.
@@ -45,8 +43,6 @@ public class ShapedRecipe extends CraftingRecipe {
* @exception IllegalArgumentException if the {@code result} is an empty item (AIR)
* @see ShapedRecipe#shape(String...)
* @see ShapedRecipe#setIngredient(char, Material)
* @see ShapedRecipe#setIngredient(char, Material, int)
* @see ShapedRecipe#setIngredient(char, MaterialData)
* @see ShapedRecipe#setIngredient(char, RecipeChoice)
*/
public ShapedRecipe(@NotNull NamespacedKey key, @NotNull ItemStack result) {

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

@@ -31,11 +31,8 @@ public class ShapelessRecipe extends CraftingRecipe {
* @param result The item you want the recipe to create.
* @exception IllegalArgumentException if the {@code result} is an empty item (AIR)
* @see ShapelessRecipe#addIngredient(Material)
* @see ShapelessRecipe#addIngredient(MaterialData)
* @see ShapelessRecipe#addIngredient(Material,int)
* @see ShapelessRecipe#addIngredient(int,Material)
* @see ShapelessRecipe#addIngredient(int,MaterialData)
* @see ShapelessRecipe#addIngredient(int,Material,int)
* @see ShapelessRecipe#addIngredient(RecipeChoice)
*/
public ShapelessRecipe(@NotNull NamespacedKey key, @NotNull ItemStack result) {
super(key, checkResult(result));
@@ -175,7 +172,7 @@ public class ShapelessRecipe extends CraftingRecipe {
/**
* Removes multiple instances of an ingredient from the list. If there are
* less instances then specified, all will be removed. Only removes exact
* fewer instances than specified, all will be removed. Only removes exact
* matches, with a data value of 0.
*
* @param count The number of copies to remove.

6
paper-api/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
View File

@@ -28,7 +28,7 @@ public class StonecuttingRecipe implements Recipe, Keyed {
}
/**
* Create a cooking recipe to craft the specified ItemStack.
* Create a Stonecutting recipe to craft the specified ItemStack.
*
* @param key The unique recipe key
* @param result The item you want the recipe to create.
@@ -42,7 +42,7 @@ public class StonecuttingRecipe implements Recipe, Keyed {
}
/**
* Sets the input of this cooking recipe.
* Sets the input of this Stonecutting recipe.
*
* @param input The input material.
* @return The changed recipe, so you can chain calls.
@@ -64,7 +64,7 @@ public class StonecuttingRecipe implements Recipe, Keyed {
}
/**
* Sets the input of this cooking recipe.
* Sets the input of this Stonecutting recipe.
*
* @param input The input choice.
* @return The changed recipe, so you can chain calls.

5
paper-api/src/main/java/org/bukkit/inventory/meta/BlockStateMeta.java
View File

@@ -32,6 +32,11 @@ public interface BlockStateMeta extends ItemMeta {
* @param blockState the block state to attach to the block.
* @throws IllegalArgumentException if the blockState is null
* or invalid for this item.
*
* @apiNote As of 1.20.5 the block state carries a copy of the item's data deviations.
* As such, setting the block state via this method will reset secondary deviations of the item meta.
* This can manifest in the addition to an existing lore failing or a change of a previously added display name.
* It is hence recommended to first mutate the block state, set it back, and then mutate the item meta.
*/
void setBlockState(@NotNull BlockState blockState);
}

6
paper-api/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java
View File

@@ -28,8 +28,7 @@ public interface CrossbowMeta extends ItemMeta {
* Removes all projectiles when given null.
*
* @param projectiles the projectiles to set
* @throws IllegalArgumentException if one of the projectiles is not an
* arrow or firework rocket
* @throws IllegalArgumentException if one of the projectiles is empty
*/
void setChargedProjectiles(@Nullable List<ItemStack> projectiles);
@@ -37,8 +36,7 @@ public interface CrossbowMeta extends ItemMeta {
* Adds a charged projectile to this item.
*
* @param item projectile
* @throws IllegalArgumentException if the projectile is not an arrow or
* firework rocket
* @throws IllegalArgumentException if the projectile is empty
*/
void addChargedProjectile(@NotNull ItemStack item);
}

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

@@ -328,7 +328,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
/**
* Gets the enchantable component. Higher values allow higher enchantments.
*
* @return max_stack_size
* @return the enchantable value
*/
int getEnchantable();
@@ -661,11 +661,6 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
/**
* Gets the item which this item will convert to when used.
* <p>
* The returned component is a snapshot of its current state and does not
* reflect a live view of what is on an item. After changing any value on
* this component, it must be set with {@link #setUseRemainder(ItemStack)}
* to apply the changes.
*
* @return remainder
*/
@@ -802,7 +797,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
* The returned component is a snapshot of its current state and does not
* reflect a live view of what is on an item. After changing any value on
* this component, it must be set with
* {@link #setJukeboxPlayable(org.bukkit.inventory.meta.components.JukeboxComponent)}
* {@link #setJukeboxPlayable(org.bukkit.inventory.meta.components.JukeboxPlayableComponent)}
* to apply the changes.
*
* @return component
@@ -811,7 +806,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
JukeboxPlayableComponent getJukeboxPlayable();
/**
* Sets the item tool.
* Sets the jukebox playable component.
*
* @param jukeboxPlayable new component
*/
@@ -838,7 +833,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
/**
* Return an immutable copy of all {@link Attribute}s and their
* {@link AttributeModifier}s for a given {@link EquipmentSlot}.<br>
* Any {@link AttributeModifier} that does have have a given
* Any {@link AttributeModifier} that does have a given
* {@link EquipmentSlot} will be returned. This is because
* AttributeModifiers without a slot are active in any slot.<br>
* If there are no attributes set for the given slot, an empty map

11
paper-api/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java
View File

@@ -8,8 +8,9 @@ import org.jetbrains.annotations.Nullable;
/**
* Represents leather armor ({@link Material#LEATHER_BOOTS}, {@link
* Material#LEATHER_CHESTPLATE}, {@link Material#LEATHER_HELMET}, or {@link
* Material#LEATHER_LEGGINGS}) that can be colored.
* Material#LEATHER_LEGGINGS}, {@link Material#LEATHER_CHESTPLATE}, {@link
* Material#LEATHER_HELMET}, {@link Material#LEATHER_HORSE_ARMOR} or {@link
* Material#WOLF_ARMOR}) that can be colored.
*/
public interface LeatherArmorMeta extends ItemMeta {
@@ -18,6 +19,9 @@ public interface LeatherArmorMeta extends ItemMeta {
* be {@link ItemFactory#getDefaultLeatherColor()}.
*
* @return the color of the armor, never null
* @apiNote The method yielding {@link ItemFactory#getDefaultLeatherColor()} is incorrect
* for {@link Material#WOLF_ARMOR} as its default color differs. Generally, it is recommended to check
* {@link #isDyed()} to determine if this leather armor is dyed than to compare this color to the default.
*/
@NotNull
Color getColor();
@@ -25,8 +29,7 @@ public interface LeatherArmorMeta extends ItemMeta {
/**
* Sets the color of the armor.
*
* @param color the color to set. Setting it to null is equivalent to
* setting it to {@link ItemFactory#getDefaultLeatherColor()}.
* @param color the color to set.
*/
void setColor(@Nullable Color color);

2
paper-api/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java
View File

@@ -3,7 +3,7 @@ package org.bukkit.inventory.meta;
import org.jetbrains.annotations.NotNull;
/**
* Represents a map that can be scalable.
* Represents an ominous bottle with an amplifier of the bad omen effect.
*/
public interface OminousBottleMeta extends ItemMeta {

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

@@ -6,8 +6,7 @@ import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.Nullable;
/**
* Represents a component which determines the cooldown applied to use of this
* item.
* Represents a component which determines the cooldown applied when using this item before it is available for use again.
*/
@ApiStatus.Experimental
public interface UseCooldownComponent extends ConfigurationSerializable {
@@ -39,7 +38,7 @@ public interface UseCooldownComponent extends ConfigurationSerializable {
/**
* Sets the custom cooldown group to be used for similar items.
*
* @param song the cooldown group
* @param group the cooldown group
*/
void setCooldownGroup(@Nullable NamespacedKey song);
void setCooldownGroup(@Nullable NamespacedKey group);
}