diff --git a/paper-api/src/main/java/org/bukkit/BanList.java b/paper-api/src/main/java/org/bukkit/BanList.java index ac38b4af28..5829aca9e5 100644 --- a/paper-api/src/main/java/org/bukkit/BanList.java +++ b/paper-api/src/main/java/org/bukkit/BanList.java @@ -38,6 +38,9 @@ public interface BanList<T> { /** * Gets a {@link BanEntry} by target. + * <p> + * Bans by name for ban type {@link Type#NAME NAME} are no longer supported and this method will return + * null when trying to request them. The replacement is bans by UUID. * * @param target entry parameter to search for * @return the corresponding entry, or null if none found @@ -59,6 +62,9 @@ public interface BanList<T> { /** * Adds a ban to this list. If a previous ban exists, this will * update the previous entry. + * <p> + * Bans by name for ban type {@link Type#NAME NAME} are no longer supported and this method will return + * null when trying to request them. The replacement is bans by UUID. * * @param target the target of the ban * @param reason reason for the ban, null indicates implementation default @@ -139,6 +145,9 @@ public interface BanList<T> { /** * Gets if a {@link BanEntry} exists for the target, indicating an active * ban status. + * <p> + * Bans by name for ban type {@link Type#NAME NAME} are no longer supported. + * The replacement is bans by UUID. * * @param target the target to find * @return true if a {@link BanEntry} exists for the target, indicating an @@ -161,6 +170,9 @@ public interface BanList<T> { /** * Removes the specified target from this list, therefore indicating a * "not banned" status. + * <p> + * Bans by name for ban type {@link Type#NAME NAME} are no longer supported. + * The replacement is bans by UUID. * * @param target the target to remove from this list */ diff --git a/paper-api/src/main/java/org/bukkit/Bukkit.java b/paper-api/src/main/java/org/bukkit/Bukkit.java index 29e13fd7c9..bacdb1742e 100644 --- a/paper-api/src/main/java/org/bukkit/Bukkit.java +++ b/paper-api/src/main/java/org/bukkit/Bukkit.java @@ -1538,6 +1538,8 @@ public final class Bukkit { /** * Gets every player that has ever played on this server. + * <p> + * <b>This method can be expensive as it loads all the player data files from the disk.</b> * * @return an array containing all previous players */ @@ -2059,7 +2061,7 @@ public final class Bukkit { * server will pause most functions after this time if there are no players * online. * <p> - * A value of less than 0 will disable the setting + * A value of less than 1 will disable the setting * * @param seconds the pause threshold in seconds */ diff --git a/paper-api/src/main/java/org/bukkit/ChunkSnapshot.java b/paper-api/src/main/java/org/bukkit/ChunkSnapshot.java index 8832a2e090..725d7944ce 100644 --- a/paper-api/src/main/java/org/bukkit/ChunkSnapshot.java +++ b/paper-api/src/main/java/org/bukkit/ChunkSnapshot.java @@ -136,7 +136,7 @@ public interface ChunkSnapshot { * Get raw biome temperature at given coordinates * * @param x X-coordinate (0-15) - * @param y Y-coordinate (0-15) + * @param y Y-coordinate (world minHeight (inclusive) - world maxHeight (exclusive)) * @param z Z-coordinate (0-15) * @return temperature at given coordinate */ diff --git a/paper-api/src/main/java/org/bukkit/HeightMap.java b/paper-api/src/main/java/org/bukkit/HeightMap.java index db6fcd635e..344b2b5d92 100644 --- a/paper-api/src/main/java/org/bukkit/HeightMap.java +++ b/paper-api/src/main/java/org/bukkit/HeightMap.java @@ -12,8 +12,7 @@ public enum HeightMap { */ MOTION_BLOCKING, /** - * The highest block that blocks motion or contains a fluid or is in the - * {@link Tag#LEAVES}. + * The highest block that blocks motion or contains a fluid, excluding leaves. */ MOTION_BLOCKING_NO_LEAVES, /** diff --git a/paper-api/src/main/java/org/bukkit/Particle.java b/paper-api/src/main/java/org/bukkit/Particle.java index bc23886a62..ecf9f941e6 100644 --- a/paper-api/src/main/java/org/bukkit/Particle.java +++ b/paper-api/src/main/java/org/bukkit/Particle.java @@ -207,7 +207,7 @@ public enum Particle implements Keyed { } /** - * Options which can be applied to redstone dust particles - a particle + * Options which can be applied to dust particles - a particle * color and size. */ public static class DustOptions { diff --git a/paper-api/src/main/java/org/bukkit/RegionAccessor.java b/paper-api/src/main/java/org/bukkit/RegionAccessor.java index 4c9fd558fb..458119a9ef 100644 --- a/paper-api/src/main/java/org/bukkit/RegionAccessor.java +++ b/paper-api/src/main/java/org/bukkit/RegionAccessor.java @@ -158,7 +158,7 @@ public interface RegionAccessor { * Creates a tree at the given {@link Location} * * @param location Location to spawn the tree - * @param random Random to use to generated the tree + * @param random Random to use to generate the tree * @param type Type of the tree to create * @return true if the tree was created successfully, otherwise false */ @@ -170,14 +170,14 @@ public interface RegionAccessor { * The provided consumer gets called for every block which gets changed * as a result of the tree generation. When the consumer gets called no * modifications to the world are done yet. Which means, that calling - * {@link #getBlockState(Location)} in the consumer while return the state + * {@link #getBlockState(Location)} in the consumer will return the state * of the block before the generation. * <p> * Modifications done to the {@link BlockState} in the consumer are respected, * which means that it is not necessary to call {@link BlockState#update()} * * @param location Location to spawn the tree - * @param random Random to use to generated the tree + * @param random Random to use to generate the tree * @param type Type of the tree to create * @param stateConsumer The consumer which should get called for every block which gets changed * @return true if the tree was created successfully, otherwise false @@ -197,7 +197,7 @@ public interface RegionAccessor { * If it returns {@code false} the block won't get set in the world. * * @param location Location to spawn the tree - * @param random Random to use to generated the tree + * @param random Random to use to generate the tree * @param type Type of the tree to create * @param statePredicate The predicate which should get used to test if a block should be set or not. * @return true if the tree was created successfully, otherwise false diff --git a/paper-api/src/main/java/org/bukkit/Server.java b/paper-api/src/main/java/org/bukkit/Server.java index 4225105fef..a506e61844 100644 --- a/paper-api/src/main/java/org/bukkit/Server.java +++ b/paper-api/src/main/java/org/bukkit/Server.java @@ -581,13 +581,10 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi * </ul> * <p> * <b>Note:</b> If set to 0, {@link SpawnCategory} mobs spawning will be disabled. - * <p> - * Minecraft default: 1. - * <br> - * <b>Note: </b> the {@link SpawnCategory#MISC} are not consider. * * @param spawnCategory the category of spawn * @return the default ticks per {@link SpawnCategory} mobs spawn value + * @throws IllegalArgumentException if the category is {@link SpawnCategory#MISC} */ public int getTicksPerSpawns(@NotNull SpawnCategory spawnCategory); @@ -1298,6 +1295,8 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi /** * Gets every player that has ever played on this server. + * <p> + * <b>This method can be expensive as it loads all the player data files from the disk.</b> * * @return an array containing all previous players */ @@ -1740,7 +1739,7 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi * Sets the pause when empty threshold seconds. To save resources, the * pause most functions after this time if there are no players online. * <p> - * A value of less than 0 will disable the setting + * A value of less than 1 will disable the setting * * @param seconds the pause threshold in seconds */ diff --git a/paper-api/src/main/java/org/bukkit/World.java b/paper-api/src/main/java/org/bukkit/World.java index e5d3ccf6e1..369e92f2b5 100644 --- a/paper-api/src/main/java/org/bukkit/World.java +++ b/paper-api/src/main/java/org/bukkit/World.java @@ -2766,7 +2766,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient /** * Find the closest nearby structure of a given {@link StructureType}. * Finding unexplored structures can, and will, block if the world is - * looking in chunks that gave not generated yet. This can lead to the world + * looking in chunks that have not generated yet. This can lead to the world * temporarily freezing while locating an unexplored structure. * <p> * The {@code radius} is not a rigid square radius. Each structure may alter @@ -2800,7 +2800,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient /** * Find the closest nearby structure of a given {@link StructureType}. * Finding unexplored structures can, and will, block if the world is - * looking in chunks that gave not generated yet. This can lead to the world + * looking in chunks that have not generated yet. This can lead to the world * temporarily freezing while locating an unexplored structure. * <p> * The {@code radius} is not a rigid square radius. Each structure may alter @@ -2833,7 +2833,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient /** * Find the closest nearby structure of a given {@link Structure}. Finding * unexplored structures can, and will, block if the world is looking in - * chunks that gave not generated yet. This can lead to the world + * chunks that have not generated yet. This can lead to the world * temporarily freezing while locating an unexplored structure. * <p> * The {@code radius} is not a rigid square radius. Each structure may alter diff --git a/paper-api/src/main/java/org/bukkit/attribute/AttributeModifier.java b/paper-api/src/main/java/org/bukkit/attribute/AttributeModifier.java index ecf3897bd2..b90af00a8e 100644 --- a/paper-api/src/main/java/org/bukkit/attribute/AttributeModifier.java +++ b/paper-api/src/main/java/org/bukkit/attribute/AttributeModifier.java @@ -129,8 +129,7 @@ public class AttributeModifier implements ConfigurationSerializable, Keyed { } /** - * Get the {@link EquipmentSlot} this AttributeModifier is active on, - * or null if this modifier is applicable for any slot. + * Get the {@link EquipmentSlotGroup} this AttributeModifier is active on. * * @return the slot */ diff --git a/paper-api/src/main/java/org/bukkit/block/Bed.java b/paper-api/src/main/java/org/bukkit/block/Bed.java index 20aaa7e15a..4677845289 100644 --- a/paper-api/src/main/java/org/bukkit/block/Bed.java +++ b/paper-api/src/main/java/org/bukkit/block/Bed.java @@ -4,7 +4,22 @@ import org.bukkit.material.Colorable; /** * Represents a captured state of a bed. - * @deprecated does not provide useful information beyond the material itself */ -@Deprecated(since = "1.13") -public interface Bed extends TileState, Colorable { } +// Paper start +// @Deprecated(since = "1.13") +public interface Bed extends TileState, Colorable { + + @Override + @org.jetbrains.annotations.NotNull org.bukkit.DyeColor getColor(); + + /** + * <b>Unsupported</b> + * + * @throws UnsupportedOperationException not supported, set the block type + */ + @Override + @org.jetbrains.annotations.Contract("_ -> fail") + @Deprecated(forRemoval = true) + void setColor(@org.bukkit.UndefinedNullability("not supported") org.bukkit.DyeColor color); +// Paper end +} diff --git a/paper-api/src/main/java/org/bukkit/block/Block.java b/paper-api/src/main/java/org/bukkit/block/Block.java index ab65d9769b..f440da5941 100644 --- a/paper-api/src/main/java/org/bukkit/block/Block.java +++ b/paper-api/src/main/java/org/bukkit/block/Block.java @@ -357,7 +357,7 @@ public interface Block extends Metadatable, Translatable { * Gets the temperature of this block. * <p> * If the raw biome temperature without adjusting for height effects is - * required then please use {@link World#getTemperature(int, int)}. + * required then please use {@link World#getTemperature(int, int, int)}. * * @return Temperature of this block */ @@ -405,7 +405,10 @@ public interface Block extends Metadatable, Translatable { boolean applyBoneMeal(@NotNull BlockFace face); /** - * Returns a list of items which would drop by destroying this block + * Returns a list of items which could drop by destroying this block. + * <p> + * The items are not guaranteed to be consistent across multiple calls to this + * method as this just uses the block type's loot table. * * @return a list of dropped items for this type of block */ @@ -413,8 +416,11 @@ public interface Block extends Metadatable, Translatable { Collection<ItemStack> getDrops(); /** - * Returns a list of items which would drop by destroying this block with - * a specific tool + * Returns a list of items which could drop by destroying this block with + * a specific tool. + * <p> + * The items are not guaranteed to be consistent across multiple calls to this + * method as this just uses the block type's loot table. * * @param tool The tool or item in hand used for digging * @return a list of dropped items for this type of block @@ -423,8 +429,11 @@ public interface Block extends Metadatable, Translatable { Collection<ItemStack> getDrops(@Nullable ItemStack tool); /** - * Returns a list of items which would drop by the entity destroying this - * block with a specific tool + * Returns a list of items which could drop by the entity destroying this + * block with a specific tool. + * <p> + * The items are not guaranteed to be consistent across multiple calls to this + * method as this just uses the block type's loot table. * * @param tool The tool or item in hand used for digging * @param entity the entity destroying the block diff --git a/paper-api/src/main/java/org/bukkit/block/data/BlockData.java b/paper-api/src/main/java/org/bukkit/block/data/BlockData.java index 29fd06cb80..cd3b3e05cc 100644 --- a/paper-api/src/main/java/org/bukkit/block/data/BlockData.java +++ b/paper-api/src/main/java/org/bukkit/block/data/BlockData.java @@ -224,7 +224,7 @@ public interface BlockData extends Cloneable { * {@link Material#REDSTONE_WIRE} -> {@link Material#REDSTONE} * {@link Material#CARROTS} -> {@link Material#CARROT} * </pre> - * @return placement material + * @return placement material or {@link Material#AIR} if it doesn't have one */ @NotNull Material getPlacementMaterial(); diff --git a/paper-api/src/main/java/org/bukkit/block/data/FaceAttachable.java b/paper-api/src/main/java/org/bukkit/block/data/FaceAttachable.java index 9599e1237b..950266b4bb 100644 --- a/paper-api/src/main/java/org/bukkit/block/data/FaceAttachable.java +++ b/paper-api/src/main/java/org/bukkit/block/data/FaceAttachable.java @@ -38,7 +38,7 @@ public interface FaceAttachable extends BlockData { */ WALL, /** - * The switch is mounted to the ceiling and pointing dowanrds. + * The switch is mounted to the ceiling and pointing downwards. */ CEILING; } diff --git a/paper-api/src/main/java/org/bukkit/block/data/type/CommandBlock.java b/paper-api/src/main/java/org/bukkit/block/data/type/CommandBlock.java index 9a7122c907..3b1dab4c1c 100644 --- a/paper-api/src/main/java/org/bukkit/block/data/type/CommandBlock.java +++ b/paper-api/src/main/java/org/bukkit/block/data/type/CommandBlock.java @@ -4,7 +4,7 @@ import org.bukkit.block.data.Directional; /** * 'conditional' denotes whether this command block is conditional or not, i.e. - * will only execute if the preceeding command block also executed successfully. + * will only execute if the preceding command block also executed successfully. */ public interface CommandBlock extends Directional { diff --git a/paper-api/src/main/java/org/bukkit/block/data/type/Gate.java b/paper-api/src/main/java/org/bukkit/block/data/type/Gate.java index 494f97d47b..ebc98607b9 100644 --- a/paper-api/src/main/java/org/bukkit/block/data/type/Gate.java +++ b/paper-api/src/main/java/org/bukkit/block/data/type/Gate.java @@ -5,7 +5,7 @@ import org.bukkit.block.data.Openable; import org.bukkit.block.data.Powerable; /** - * 'in_wall" indicates if the fence gate is attached to a wall, and if true the + * 'in_wall' indicates if the fence gate is attached to a wall, and if true the * texture is lowered by a small amount to blend in better. */ public interface Gate extends Directional, Openable, Powerable { diff --git a/paper-api/src/main/java/org/bukkit/block/data/type/Switch.java b/paper-api/src/main/java/org/bukkit/block/data/type/Switch.java index df8c2d60e7..16ced762f4 100644 --- a/paper-api/src/main/java/org/bukkit/block/data/type/Switch.java +++ b/paper-api/src/main/java/org/bukkit/block/data/type/Switch.java @@ -21,7 +21,7 @@ public interface Switch extends Directional, FaceAttachable, Powerable { * Sets the value of the 'face' property. * * @param face the new 'face' value - * @deprecated use {@link #getAttachedFace()} + * @deprecated use {@link #setAttachedFace(AttachedFace)} */ @Deprecated(since = "1.15.2") void setFace(@NotNull Face face); @@ -42,7 +42,7 @@ public interface Switch extends Directional, FaceAttachable, Powerable { */ WALL, /** - * The switch is mounted to the ceiling and pointing dowanrds. + * The switch is mounted to the ceiling and pointing downwards. */ CEILING; } diff --git a/paper-api/src/main/java/org/bukkit/entity/ArmorStand.java b/paper-api/src/main/java/org/bukkit/entity/ArmorStand.java index 6a1d563d1b..c727b2d40e 100644 --- a/paper-api/src/main/java/org/bukkit/entity/ArmorStand.java +++ b/paper-api/src/main/java/org/bukkit/entity/ArmorStand.java @@ -360,5 +360,8 @@ public interface ArmorStand extends LivingEntity { * @param move {@code true} if this armour stand can move, {@code false} otherwise */ void setCanMove(boolean move); + + @Override + org.bukkit.inventory.@NotNull EntityEquipment getEquipment(); // Paper end } diff --git a/paper-api/src/main/java/org/bukkit/entity/Arrow.java b/paper-api/src/main/java/org/bukkit/entity/Arrow.java index a292579c9f..38e6a8dbb2 100644 --- a/paper-api/src/main/java/org/bukkit/entity/Arrow.java +++ b/paper-api/src/main/java/org/bukkit/entity/Arrow.java @@ -93,7 +93,7 @@ public interface Arrow extends AbstractArrow { * Removes a custom potion effect from this arrow. * * @param type the potion effect type to remove - * @return true if the an effect was removed as a result of this call + * @return true if the effect was removed as a result of this call * @throws IllegalArgumentException if this operation would leave the Arrow * in a state with no Custom Effects and PotionType.UNCRAFTABLE */ diff --git a/paper-api/src/main/java/org/bukkit/entity/EnderDragon.java b/paper-api/src/main/java/org/bukkit/entity/EnderDragon.java index 1e56aef918..92cd35c87b 100644 --- a/paper-api/src/main/java/org/bukkit/entity/EnderDragon.java +++ b/paper-api/src/main/java/org/bukkit/entity/EnderDragon.java @@ -30,7 +30,7 @@ public interface EnderDragon extends ComplexLivingEntity, Boss, Mob, Enemy { */ FLY_TO_PORTAL, /** - * The dragon will land on on the portal. If the dragon is not near + * The dragon will land on the portal. If the dragon is not near * the portal, it will fly to it before mounting. */ LAND_ON_PORTAL, diff --git a/paper-api/src/main/java/org/bukkit/entity/Entity.java b/paper-api/src/main/java/org/bukkit/entity/Entity.java index 411297f665..45d408f519 100644 --- a/paper-api/src/main/java/org/bukkit/entity/Entity.java +++ b/paper-api/src/main/java/org/bukkit/entity/Entity.java @@ -180,9 +180,13 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent public List<org.bukkit.entity.Entity> getNearbyEntities(double x, double y, double z); /** - * Returns a unique id for this entity + * Returns the network protocol ID for this entity. This is + * not to be used as an identifier for the entity except in + * network-related operations. Use {@link #getUniqueId()} as + * an entity identifier instead. * - * @return Entity id + * @return the network protocol ID + * @see #getUniqueId() */ public int getEntityId(); diff --git a/paper-api/src/main/java/org/bukkit/entity/HumanEntity.java b/paper-api/src/main/java/org/bukkit/entity/HumanEntity.java index b21f42e653..c90a0a00be 100644 --- a/paper-api/src/main/java/org/bukkit/entity/HumanEntity.java +++ b/paper-api/src/main/java/org/bukkit/entity/HumanEntity.java @@ -22,6 +22,11 @@ import org.jetbrains.annotations.Nullable; */ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder { + // Paper start + @Override + org.bukkit.inventory.@NotNull EntityEquipment getEquipment(); + // Paper end + /** * Returns the name of this player * diff --git a/paper-api/src/main/java/org/bukkit/entity/ItemFrame.java b/paper-api/src/main/java/org/bukkit/entity/ItemFrame.java index b688b3856c..c275b881cb 100644 --- a/paper-api/src/main/java/org/bukkit/entity/ItemFrame.java +++ b/paper-api/src/main/java/org/bukkit/entity/ItemFrame.java @@ -75,7 +75,7 @@ public interface ItemFrame extends Hanging { public void setRotation(@NotNull Rotation rotation) throws IllegalArgumentException; /** - * Returns whether the item frame is be visible or not. + * Returns whether the item frame is visible or not. * * @return whether the item frame is visible or not */ diff --git a/paper-api/src/main/java/org/bukkit/entity/LivingEntity.java b/paper-api/src/main/java/org/bukkit/entity/LivingEntity.java index 598c88f02a..4b75a5e1ce 100644 --- a/paper-api/src/main/java/org/bukkit/entity/LivingEntity.java +++ b/paper-api/src/main/java/org/bukkit/entity/LivingEntity.java @@ -502,7 +502,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource /** * Sets the leash on this entity to be held by the supplied entity. * <p> - * This method has no effect on EnderDragons, Withers, Players, or Bats. + * This method has no effect on players. * Non-living entities excluding leashes will not persist as leash * holders. * diff --git a/paper-api/src/main/java/org/bukkit/entity/Mob.java b/paper-api/src/main/java/org/bukkit/entity/Mob.java index f3f62e13cc..ad5dbf310f 100644 --- a/paper-api/src/main/java/org/bukkit/entity/Mob.java +++ b/paper-api/src/main/java/org/bukkit/entity/Mob.java @@ -9,6 +9,10 @@ import org.jetbrains.annotations.Nullable; */ public interface Mob extends LivingEntity, Lootable { + // Paper start + @Override + org.bukkit.inventory.@org.jetbrains.annotations.NotNull EntityEquipment getEquipment(); + // Paper end /** * Instructs this Mob to set the specified LivingEntity as its target. * <p> diff --git a/paper-api/src/main/java/org/bukkit/entity/PigZombie.java b/paper-api/src/main/java/org/bukkit/entity/PigZombie.java index ae9eaaa8e3..b2ec535bb1 100644 --- a/paper-api/src/main/java/org/bukkit/entity/PigZombie.java +++ b/paper-api/src/main/java/org/bukkit/entity/PigZombie.java @@ -44,8 +44,6 @@ public interface PigZombie extends Zombie { /** * <b>Not applicable to this entity</b> - * - * @return UnsuppotedOperationException */ @Override public int getConversionTime(); diff --git a/paper-api/src/main/java/org/bukkit/entity/Player.java b/paper-api/src/main/java/org/bukkit/entity/Player.java index e014582d73..5b12fa8c41 100644 --- a/paper-api/src/main/java/org/bukkit/entity/Player.java +++ b/paper-api/src/main/java/org/bukkit/entity/Player.java @@ -492,15 +492,15 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM /** * Saves the players current location, health, inventory, motion, and - * other information into the uuid.dat file, in the <main - * world>/playerdata folder. + * other information into the <uuid>.dat file, in the + * <level-name>/playerdata/ folder. */ public void saveData(); /** * Loads the players current location, health, inventory, motion, and - * other information from the uuid.dat file, in the <main - * world>/playerdata folder. + * other information from the <uuid>.dat file, in the + * <level-name>/playerdata/ folder. * <p> * Note: This will overwrite the players current inventory, health, * motion, etc, with the state from the saved dat file. @@ -861,7 +861,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM /** * Plays an effect to just this player. * - * @param <T> the data based based on the type of the effect + * @param <T> the data based on the type of the effect * @param loc the location to play the effect at * @param effect the {@link Effect} * @param data a data bit needed for some effects @@ -1272,7 +1272,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM * * Use supplied alternative character to the section symbol to represent legacy color codes. * - * @param alternateChar Alternate symbol such as '&' + * @param alternateChar Alternate symbol such as '&' * @param message The message to send * @deprecated use {@link #sendActionBar(net.kyori.adventure.text.Component)} */ @@ -1745,7 +1745,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM /** * Allows this player to see a player that was previously hidden. If - * another another plugin had hidden the player too, then the player will + * another plugin had hidden the player too, then the player will * remain hidden until the other plugin calls this method too. * * @param plugin Plugin that wants to show the player @@ -1772,7 +1772,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM /** * Allows this player to see an entity that was previously hidden. If - * another another plugin had hidden the entity too, then the entity will + * another plugin had hidden the entity too, then the entity will * remain hidden until the other plugin calls this method too. * * @param plugin Plugin that wants to show the entity @@ -1855,9 +1855,6 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM * case this method will have no affect on them. Use the * {@link PlayerResourcePackStatusEvent} to figure out whether or not * the player loaded the pack! - * <li>There is no concept of resetting texture packs back to default - * within Minecraft, so players will have to relog to do so or you - * have to send an empty pack. * <li>The request is send with "null" as the hash. This might result * in newer versions not loading the pack correctly. * </ul> @@ -1891,9 +1888,6 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM * case this method will have no affect on them. Use the * {@link PlayerResourcePackStatusEvent} to figure out whether or not * the player loaded the pack! - * <li>There is no concept of resetting resource packs back to default - * within Minecraft, so players will have to relog to do so or you - * have to send an empty pack. * <li>The request is send with empty string as the hash. This might result * in newer versions not loading the pack correctly. * </ul> @@ -1930,9 +1924,6 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM * case this method will have no affect on them. Use the * {@link PlayerResourcePackStatusEvent} to figure out whether or not * the player loaded the pack! - * <li>There is no concept of resetting resource packs back to default - * within Minecraft, so players will have to relog to do so or you - * have to send an empty pack. * <li>The request is sent with empty string as the hash when the hash is * not provided. This might result in newer versions not loading the * pack correctly. diff --git a/paper-api/src/main/java/org/bukkit/entity/Slime.java b/paper-api/src/main/java/org/bukkit/entity/Slime.java index a5ad3250ce..0a2d603bf6 100644 --- a/paper-api/src/main/java/org/bukkit/entity/Slime.java +++ b/paper-api/src/main/java/org/bukkit/entity/Slime.java @@ -11,6 +11,16 @@ public interface Slime extends Mob, Enemy { public int getSize(); /** + * Setting the size of the slime (regardless of previous size) + * will set the following attributes: + * <ul> + * <li>{@link org.bukkit.attribute.Attribute#MAX_HEALTH}</li> + * <li>{@link org.bukkit.attribute.Attribute#MOVEMENT_SPEED}</li> + * <li>{@link org.bukkit.attribute.Attribute#ATTACK_DAMAGE}</li> + * </ul> + * to their per-size defaults and heal the + * slime to its max health (assuming it's alive). + * * @param sz The new size of the slime. */ public void setSize(int sz); diff --git a/paper-api/src/main/java/org/bukkit/entity/Sniffer.java b/paper-api/src/main/java/org/bukkit/entity/Sniffer.java index af5110b416..15a0a733b0 100644 --- a/paper-api/src/main/java/org/bukkit/entity/Sniffer.java +++ b/paper-api/src/main/java/org/bukkit/entity/Sniffer.java @@ -12,8 +12,6 @@ public interface Sniffer extends Animals { /** * Gets the locations explored by the sniffer. - * <br> - * <b>Note:</b> the returned locations use sniffer's current world. * * @return a collection of locations */ @@ -22,9 +20,6 @@ public interface Sniffer extends Animals { /** * Remove a location of the explored locations. - * <br> - * <b>Note:</b> the location must be in the sniffer's current world for this - * method to have any effect. * * @param location the location to remove * @see #getExploredLocations() diff --git a/paper-api/src/main/java/org/bukkit/entity/Villager.java b/paper-api/src/main/java/org/bukkit/entity/Villager.java index c48f13cc8e..af4582f3e4 100644 --- a/paper-api/src/main/java/org/bukkit/entity/Villager.java +++ b/paper-api/src/main/java/org/bukkit/entity/Villager.java @@ -224,7 +224,7 @@ public interface Villager extends AbstractVillager { */ Profession NITWIT = getProfession("nitwit"); /** - * Sheperd profession. Wears a brown robe. Shepherds primarily trade for + * Shepherd profession. Wears a brown robe. Shepherds primarily trade for * wool items, and shears. */ Profession SHEPHERD = getProfession("shepherd"); diff --git a/paper-api/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java b/paper-api/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java index a0f6f1af30..7e21548cac 100644 --- a/paper-api/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java @@ -10,15 +10,19 @@ import org.bukkit.event.HandlerList; import org.jetbrains.annotations.NotNull; /** - * Called if a block broken by a player drops an item. + * Called after a block is broken by a player and potential drops are computed, even if said blocks loot table + * does not define any drops at the point the event is constructed. * * If the block break is cancelled, this event won't be called. * - * If isDropItems in BlockBreakEvent is set to false, this event won't be + * If isDropItems in {@link org.bukkit.event.block.BlockBreakEvent} is set to false, this event won't be * called. * + * If a block is broken and isDropItems is set to true, this event will be called even if the block does + * not drop any items, for example glass broken by hand. In this case, #getItems() will be empty. + * * This event will also be called if the player breaks a multi block structure, - * for example a torch on top of a stone. Both items will have an event call. + * for example a torch on top of a stone. Both items will be included in the #getItems() list. * * The Block is already broken as this event is called, so #getBlock() will be * AIR in most cases. Use #getBlockState() for more Information about the broken diff --git a/paper-api/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java b/paper-api/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java index 1df172c0bb..254d549f95 100644 --- a/paper-api/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java @@ -14,6 +14,9 @@ import org.jetbrains.annotations.NotNull; * Note that due to the nature of explosions, {@link #getBlock()} will always be * an air block. {@link #getExplodedBlockState()} should be used to get * information about the block state that exploded. + * <p> + * The event isn't called if the {@link org.bukkit.GameRule#MOB_GRIEFING} + * is disabled as no block interaction will occur. */ public class BlockExplodeEvent extends BlockEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); diff --git a/paper-api/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java b/paper-api/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java index 0392cc3a00..23b3f44ab0 100644 --- a/paper-api/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java @@ -34,7 +34,7 @@ public class BlockPistonRetractEvent extends BlockPistonEvent { /** * Get an immutable list of the blocks which will be moved by the - * extending. + * retracting. * * @return Immutable list of the moved blocks. */ diff --git a/paper-api/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java b/paper-api/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java index 77215c1dd2..3bfd0f6edc 100644 --- a/paper-api/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java @@ -114,7 +114,7 @@ public class BlockPlaceEvent extends BlockEvent implements Cancellable { /** * Gets the value whether the player would be allowed to build here. - * Defaults to spawn if the server was going to stop them (such as, the + * Defaults to false if the server was going to stop them (such as, the * player is in Spawn). Note that this is an entirely different check * than BLOCK_CANBUILD, as this refers to a player, not universe-physics * rule like cactus on dirt. diff --git a/paper-api/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java b/paper-api/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java index a722e090e7..4c8f388897 100644 --- a/paper-api/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java @@ -81,7 +81,7 @@ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellab /** * Get a list of available {@link EnchantmentOffer} for the player. You can * modify the values to change the available offers for the player. An offer - * may be null, if there isn't a enchantment offer at a specific slot. There + * may be null, if there isn't an enchantment offer at a specific slot. There * are 3 slots in the enchantment table available to modify. * * @return list of available enchantment offers diff --git a/paper-api/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java b/paper-api/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java index a37febd0d4..9cee218b9e 100644 --- a/paper-api/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java @@ -8,7 +8,7 @@ import org.bukkit.event.HandlerList; import org.jetbrains.annotations.NotNull; /** - * Called when a lingering potion applies it's effects. Happens + * Called when a lingering potion applies its effects. Happens * once every 5 ticks */ public class AreaEffectCloudApplyEvent extends EntityEvent implements Cancellable { diff --git a/paper-api/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java b/paper-api/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java index c746c2e73a..5d2597378d 100644 --- a/paper-api/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java @@ -158,11 +158,12 @@ public class CreatureSpawnEvent extends EntitySpawnEvent { */ DROWNED, /** - * When an cow is spawned by shearing a mushroom cow + * When a cow is spawned by shearing a mushroom cow */ SHEARED, /** - * When eg an effect cloud is spawned as a result of a creeper exploding + * When an entity is spawned as a result of an explosion. Like an area effect cloud from + * a creeper or a dragon fireball. */ EXPLOSION, /** diff --git a/paper-api/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java b/paper-api/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java index 0a3699226b..971093bd25 100644 --- a/paper-api/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java @@ -12,6 +12,10 @@ import org.jetbrains.annotations.Nullable; /** * Called when an entity is damaged by a block + * <p> + * For explosions, the Block returned by {@link #getDamager()} has + * already been cleared. See {@link #getDamagerBlockState()} for a snapshot + * of the block if it has already been changed. */ public class EntityDamageByBlockEvent extends EntityDamageEvent { private final Block damager; @@ -51,6 +55,9 @@ public class EntityDamageByBlockEvent extends EntityDamageEvent { /** * Returns the captured BlockState of the block that damaged the player. + * <p> + * This block state is not placed so {@link org.bukkit.block.BlockState#isPlaced} + * will be false. * * @return the block state */ diff --git a/paper-api/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java b/paper-api/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java index fc2158793a..50161d313c 100644 --- a/paper-api/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java @@ -10,7 +10,9 @@ import org.bukkit.event.HandlerList; import org.jetbrains.annotations.NotNull; /** - * Called when an entity explodes + * Called when an entity explodes interacting with blocks. The + * event isn't called if the {@link org.bukkit.GameRule#MOB_GRIEFING} + * is disabled as no block interaction will occur. */ public class EntityExplodeEvent extends EntityEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); diff --git a/paper-api/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java b/paper-api/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java index c866df03d6..94ee5a3354 100644 --- a/paper-api/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java @@ -7,7 +7,7 @@ import org.bukkit.event.HandlerList; import org.jetbrains.annotations.NotNull; /** - * Thrown when a entity picks an item up from the ground + * Thrown when an entity picks an item up from the ground */ public class EntityPickupItemEvent extends EntityEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); diff --git a/paper-api/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java b/paper-api/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java index 4f11695607..a7bd15d51a 100644 --- a/paper-api/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java @@ -11,7 +11,7 @@ import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; /** - * Triggered when a entity is created in the world by a player "placing" an item + * Triggered when an entity is created in the world by a player "placing" an item * on a block. * <br> * Note that this event is currently only fired for four specific placements: diff --git a/paper-api/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java b/paper-api/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java index 31a5515c08..d743cc5ee3 100644 --- a/paper-api/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java @@ -133,7 +133,7 @@ public class EntityPotionEffectEvent extends EntityEvent implements Cancellable public enum Action { /** - * When the potion effect is added because the entity didn't have it's + * When the potion effect is added because the entity didn't have its * type. */ ADDED, @@ -237,7 +237,7 @@ public class EntityPotionEffectEvent extends EntityEvent implements Cancellable */ SPIDER_SPAWN, /** - * When the entity gets effects from a totem item saving it's life. + * When the entity gets effects from a totem item saving its life. */ TOTEM, /** diff --git a/paper-api/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java b/paper-api/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java index d51d2ec1d0..7ecff9fcee 100644 --- a/paper-api/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java @@ -105,7 +105,7 @@ public class EntityRegainHealthEvent extends EntityEvent implements Cancellable */ SATIATED, /** - * When a player regains health from eating consumables + * When an animal regains health from eating consumables */ EATING, /** diff --git a/paper-api/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java b/paper-api/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java index 842cfd3e98..808142232a 100644 --- a/paper-api/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java @@ -156,7 +156,7 @@ public class EntityTargetEvent extends EntityEvent implements Cancellable { FOLLOW_LEADER, /** * When another entity tempts this entity by having a desired item such - * as wheat in it's hand. + * as wheat in its hand. */ TEMPT, /** diff --git a/paper-api/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java b/paper-api/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java index c17ff41a68..bd67b7cba7 100644 --- a/paper-api/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java @@ -10,8 +10,7 @@ import org.jetbrains.annotations.NotNull; /** * Stores all data related to the bartering interaction with a piglin. * - * This event can be triggered by a piglin picking up an item that's on its - * bartering list. + * Called when a piglin completes a barter. */ public class PiglinBarterEvent extends EntityEvent implements Cancellable { diff --git a/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java b/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java index bc71bc2d3a..24077da8e6 100644 --- a/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java @@ -8,7 +8,9 @@ import org.bukkit.inventory.ItemStack; import org.jetbrains.annotations.NotNull; /** - * Called when an ItemStack is successfully burned as fuel in a furnace. + * Called when an ItemStack is successfully burned as fuel in a furnace-like block such as a + * {@link org.bukkit.block.Furnace}, {@link org.bukkit.block.Smoker}, or + * {@link org.bukkit.block.BlastFurnace}. */ public class FurnaceBurnEvent extends BlockEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); diff --git a/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java b/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java index 65db4991bd..5ffd28fd24 100644 --- a/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java @@ -9,7 +9,9 @@ import org.bukkit.material.MaterialData; import org.jetbrains.annotations.NotNull; /** - * This event is called when a player takes items out of the furnace + * This event is called when a player takes items out of a furnace-like block such as a + * {@link org.bukkit.block.Furnace}, {@link org.bukkit.block.Smoker}, or + * {@link org.bukkit.block.BlastFurnace}. */ public class FurnaceExtractEvent extends BlockExpEvent { private final Player player; diff --git a/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java b/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java index 066e7dd9a3..f8f9b08a0b 100644 --- a/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java @@ -6,7 +6,9 @@ import org.bukkit.inventory.ItemStack; import org.jetbrains.annotations.NotNull; /** - * Called when an ItemStack is successfully smelted in a furnace. + * Called when an ItemStack is successfully smelted in a furnace-like block + * such as a {@link org.bukkit.block.Furnace}, {@link org.bukkit.block.Smoker}, + * or {@link org.bukkit.block.BlastFurnace}. */ public class FurnaceSmeltEvent extends BlockCookEvent { diff --git a/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java b/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java index 1440c61155..0808e7aeff 100644 --- a/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java @@ -8,7 +8,10 @@ import org.bukkit.inventory.ItemStack; import org.jetbrains.annotations.NotNull; /** - * Called when a Furnace starts smelting. + * Called when any of the furnace-like blocks start smelting. + * <p> + * Furnace-like blocks are {@link org.bukkit.block.Furnace}, + * {@link org.bukkit.block.Smoker}, and {@link org.bukkit.block.BlastFurnace}. */ public class FurnaceStartSmeltEvent extends InventoryBlockStartEvent { private static final HandlerList handlers = new HandlerList(); diff --git a/paper-api/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java b/paper-api/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java index e1f0ae392c..5832c610e4 100644 --- a/paper-api/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java @@ -16,12 +16,16 @@ import org.jetbrains.annotations.Nullable; /** * This event is called when a player clicks in an inventory. * <p> + * In case of a drag action within an inventory, InventoryClickEvent is never called. + * Instead, {@link InventoryDragEvent} is called at the end of the drag. + * <p> * Because InventoryClickEvent occurs within a modification of the Inventory, * not all Inventory related methods are safe to use. * <p> - * The following should never be invoked by an EventHandler for - * InventoryClickEvent using the HumanEntity or InventoryView associated with - * this event: + * Methods that change the view a player is looking at should never be invoked + * by an EventHandler for InventoryClickEvent using the HumanEntity or + * InventoryView associated with this event. + * Examples of these include: * <ul> * <li>{@link HumanEntity#closeInventory()} * <li>{@link HumanEntity#openInventory(Inventory)} @@ -92,7 +96,7 @@ public class InventoryClickEvent extends InventoryInteractEvent { /** * Gets the ItemStack currently in the clicked slot. * - * @return the item in the clicked + * @return the item in the clicked slot */ @Nullable public ItemStack getCurrentItem() { diff --git a/paper-api/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java b/paper-api/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java index 5861247c1b..c0cc82d983 100644 --- a/paper-api/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java @@ -7,7 +7,26 @@ import org.bukkit.inventory.InventoryView; import org.jetbrains.annotations.NotNull; /** - * Represents a player related inventory event + * This event is called when a player closes an inventory. + * <p> + * Because InventoryCloseEvent occurs within a modification of the Inventory, + * not all Inventory related methods are safe to use. + * <p> + * Methods that change the view a player is looking at should never be invoked + * by an EventHandler for InventoryCloseEvent using the HumanEntity or + * InventoryView associated with this event. + * Examples of these include: + * <ul> + * <li>{@link HumanEntity#closeInventory()} + * <li>{@link HumanEntity#openInventory(org.bukkit.inventory.Inventory)} + * <li>{@link HumanEntity#openWorkbench(org.bukkit.Location, boolean)} + * <li>{@link HumanEntity#openEnchanting(org.bukkit.Location, boolean)} + * <li>{@link InventoryView#close()} + * </ul> + * To invoke one of these methods, schedule a task using + * {@link org.bukkit.scheduler.BukkitScheduler#runTask(org.bukkit.plugin.Plugin, Runnable)}, which will run the task + * on the next tick. Also be aware that this is not an exhaustive list, and + * other methods could potentially create issues as well. */ public class InventoryCloseEvent extends InventoryEvent { private static final HandlerList handlers = new HandlerList(); diff --git a/paper-api/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java b/paper-api/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java index 9013d04350..ceae092eb7 100644 --- a/paper-api/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java @@ -7,7 +7,7 @@ import org.bukkit.inventory.InventoryView; import org.jetbrains.annotations.NotNull; /** - * Represents a player related inventory event + * Called when a player opens an inventory */ public class InventoryOpenEvent extends InventoryEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); diff --git a/paper-api/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java b/paper-api/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java index 08a7c564fe..8a5be3f032 100644 --- a/paper-api/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java @@ -24,6 +24,20 @@ public class PrepareAnvilEvent extends PrepareInventoryResultEvent { return (AnvilInventory) super.getInventory(); } + /** + * {@inheritDoc} + * + * <p> + * Note: by default custom recipes in anvil are disabled + * you should define a repair cost on the anvil inventory + * greater or equals to zero in order to allow that. + * + * @param result result item + */ + public void setResult(@Nullable ItemStack result) { + super.setResult(result); + } + @NotNull @Override public AnvilView getView() { diff --git a/paper-api/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java b/paper-api/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java index c3eb020498..9eb2c2a1fe 100644 --- a/paper-api/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java @@ -106,7 +106,9 @@ public class PlayerCommandPreprocessEvent extends PlayerEvent implements Cancell * * @param player New player which this event will execute as * @throws IllegalArgumentException if the player provided is null + * @deprecated Only works for sign commands; use {@link Player#performCommand(String)}, including those cases */ + @Deprecated(forRemoval = true) public void setPlayer(@NotNull final Player player) throws IllegalArgumentException { Preconditions.checkArgument(player != null, "Player cannot be null"); this.player = player; @@ -123,11 +125,10 @@ public class PlayerCommandPreprocessEvent extends PlayerEvent implements Cancell * unmodifiable set. * * @return All Players who will see this chat message - * @deprecated This method is provided for backward compatibility with no - * guarantee to the effect of viewing or modifying the set. + * @deprecated This is simply the online players. Modifications have no effect */ @NotNull - @Deprecated(since = "1.3.1") + @Deprecated(since = "1.3.1", forRemoval = true) public Set<Player> getRecipients() { return recipients; } diff --git a/paper-api/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java b/paper-api/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java index e4c32b21ab..e58fecf0fe 100644 --- a/paper-api/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java +++ b/paper-api/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java @@ -6,8 +6,9 @@ import org.bukkit.event.HandlerList; import org.jetbrains.annotations.NotNull; /** - * Called when a player takes action on a resource pack request sent via - * {@link Player#setResourcePack(java.lang.String)}. + * Called when a player takes action on a resource pack request. + * @see Player#setResourcePack(String, String) + * @see Player#setResourcePack(String, String, boolean) */ public class PlayerResourcePackStatusEvent extends PlayerEvent { diff --git a/paper-api/src/main/java/org/bukkit/generator/ChunkGenerator.java b/paper-api/src/main/java/org/bukkit/generator/ChunkGenerator.java index 4b952b0178..b4dab4cf52 100644 --- a/paper-api/src/main/java/org/bukkit/generator/ChunkGenerator.java +++ b/paper-api/src/main/java/org/bukkit/generator/ChunkGenerator.java @@ -627,7 +627,7 @@ public abstract class ChunkGenerator { * Get the biome at x, y, z within chunk being generated * * @param x the x location in the chunk from 0-15 inclusive - * @param y the y location in the chunk from minimum (inclusive) - + * @param y the y location in the chunk from minHeight (inclusive) - * maxHeight (exclusive) * @param z the z location in the chunk from 0-15 inclusive * @return Biome value diff --git a/paper-api/src/main/java/org/bukkit/inventory/EntityEquipment.java b/paper-api/src/main/java/org/bukkit/inventory/EntityEquipment.java index 37298cec02..720038083f 100644 --- a/paper-api/src/main/java/org/bukkit/inventory/EntityEquipment.java +++ b/paper-api/src/main/java/org/bukkit/inventory/EntityEquipment.java @@ -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 diff --git a/paper-api/src/main/java/org/bukkit/inventory/ItemFlag.java b/paper-api/src/main/java/org/bukkit/inventory/ItemFlag.java index 8453bd058d..1b3580d186 100644 --- a/paper-api/src/main/java/org/bukkit/inventory/ItemFlag.java +++ b/paper-api/src/main/java/org/bukkit/inventory/ItemFlag.java @@ -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; } diff --git a/paper-api/src/main/java/org/bukkit/inventory/PlayerInventory.java b/paper-api/src/main/java/org/bukkit/inventory/PlayerInventory.java index 6933fb24ea..b1f4b8f266 100644 --- a/paper-api/src/main/java/org/bukkit/inventory/PlayerInventory.java +++ b/paper-api/src/main/java/org/bukkit/inventory/PlayerInventory.java @@ -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() diff --git a/paper-api/src/main/java/org/bukkit/inventory/ShapedRecipe.java b/paper-api/src/main/java/org/bukkit/inventory/ShapedRecipe.java index 83b08fa8a4..64916d17ee 100644 --- a/paper-api/src/main/java/org/bukkit/inventory/ShapedRecipe.java +++ b/paper-api/src/main/java/org/bukkit/inventory/ShapedRecipe.java @@ -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) { diff --git a/paper-api/src/main/java/org/bukkit/inventory/ShapelessRecipe.java b/paper-api/src/main/java/org/bukkit/inventory/ShapelessRecipe.java index 969710cc69..354af77509 100644 --- a/paper-api/src/main/java/org/bukkit/inventory/ShapelessRecipe.java +++ b/paper-api/src/main/java/org/bukkit/inventory/ShapelessRecipe.java @@ -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. diff --git a/paper-api/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java b/paper-api/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java index 07c3dff4d6..597a18a767 100644 --- a/paper-api/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java +++ b/paper-api/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java @@ -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. diff --git a/paper-api/src/main/java/org/bukkit/inventory/meta/BlockStateMeta.java b/paper-api/src/main/java/org/bukkit/inventory/meta/BlockStateMeta.java index e7d905b114..c7d3041221 100644 --- a/paper-api/src/main/java/org/bukkit/inventory/meta/BlockStateMeta.java +++ b/paper-api/src/main/java/org/bukkit/inventory/meta/BlockStateMeta.java @@ -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); } diff --git a/paper-api/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java b/paper-api/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java index 35c6594fd1..d58719ee75 100644 --- a/paper-api/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java +++ b/paper-api/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java @@ -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); } diff --git a/paper-api/src/main/java/org/bukkit/inventory/meta/ItemMeta.java b/paper-api/src/main/java/org/bukkit/inventory/meta/ItemMeta.java index 753a756525..c083ac4344 100644 --- a/paper-api/src/main/java/org/bukkit/inventory/meta/ItemMeta.java +++ b/paper-api/src/main/java/org/bukkit/inventory/meta/ItemMeta.java @@ -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 diff --git a/paper-api/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java b/paper-api/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java index c1676991c3..c701d5fbc5 100644 --- a/paper-api/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java +++ b/paper-api/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java @@ -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); diff --git a/paper-api/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java b/paper-api/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java index 43f0df04f3..5c741228b2 100644 --- a/paper-api/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java +++ b/paper-api/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java @@ -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 { diff --git a/paper-api/src/main/java/org/bukkit/inventory/meta/components/UseCooldownComponent.java b/paper-api/src/main/java/org/bukkit/inventory/meta/components/UseCooldownComponent.java index 4086a41389..172032e56e 100644 --- a/paper-api/src/main/java/org/bukkit/inventory/meta/components/UseCooldownComponent.java +++ b/paper-api/src/main/java/org/bukkit/inventory/meta/components/UseCooldownComponent.java @@ -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); } diff --git a/paper-api/src/main/java/org/bukkit/plugin/Plugin.java b/paper-api/src/main/java/org/bukkit/plugin/Plugin.java index 8c76716249..68a0ed5f0e 100644 --- a/paper-api/src/main/java/org/bukkit/plugin/Plugin.java +++ b/paper-api/src/main/java/org/bukkit/plugin/Plugin.java @@ -18,7 +18,7 @@ import org.jetbrains.annotations.Nullable; */ public interface Plugin extends TabExecutor { /** - * Returns the folder that the plugin data's files are located in. The + * Returns the folder that the plugin data files are located in. The * folder may not yet exist. * * @return The folder @@ -27,9 +27,9 @@ public interface Plugin extends TabExecutor { public File getDataFolder(); /** - * Returns the plugin.yaml file containing the details for this plugin + * Returns the plugin.yml file containing the details for this plugin * - * @return Contents of the plugin.yaml file + * @return Contents of the plugin.yml file * @deprecated May be inaccurate due to different plugin implementations. * @see Plugin#getPluginMeta() */ diff --git a/paper-api/src/main/java/org/bukkit/plugin/java/JavaPlugin.java b/paper-api/src/main/java/org/bukkit/plugin/java/JavaPlugin.java index 2a14522c48..7f17337b9f 100644 --- a/paper-api/src/main/java/org/bukkit/plugin/java/JavaPlugin.java +++ b/paper-api/src/main/java/org/bukkit/plugin/java/JavaPlugin.java @@ -69,7 +69,7 @@ public abstract class JavaPlugin extends PluginBase { } /** - * Returns the folder that the plugin data's files are located in. The + * Returns the folder that the plugin data files are located in. The * folder may not yet exist. * * @return The folder. @@ -127,9 +127,9 @@ public abstract class JavaPlugin extends PluginBase { } /** - * Returns the plugin.yaml file containing the details for this plugin + * Returns the plugin.yml file containing the details for this plugin * - * @return Contents of the plugin.yaml file + * @return Contents of the plugin.yml file * @deprecated No longer applicable to all types of plugins */ @NotNull diff --git a/paper-api/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java b/paper-api/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java index b84b37fe27..281ae60a6b 100644 --- a/paper-api/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java +++ b/paper-api/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java @@ -31,7 +31,8 @@ public interface PluginMessageRecipient { /** * Gets a set containing all the Plugin Channels that this client is - * listening on. + * listening on. Does not contain the BungeeCord channel due to its + * special status. * * @return Set containing all the channels that this client may accept. */ diff --git a/paper-api/src/main/java/org/bukkit/projectiles/ProjectileSource.java b/paper-api/src/main/java/org/bukkit/projectiles/ProjectileSource.java index eabd8b926e..8557bfefaf 100644 --- a/paper-api/src/main/java/org/bukkit/projectiles/ProjectileSource.java +++ b/paper-api/src/main/java/org/bukkit/projectiles/ProjectileSource.java @@ -12,6 +12,10 @@ public interface ProjectileSource { /** * Launches a {@link Projectile} from the ProjectileSource. + * <p> + * The family of launchProjectile methods only promise the ability to launch projectile types + * that the {@link ProjectileSource} is capable of firing in vanilla. + * Any other types of projectiles *may* be implemented but are not part of the method contract. * * @param <T> a projectile subclass * @param projectile class of the projectile to launch @@ -23,6 +27,10 @@ public interface ProjectileSource { /** * Launches a {@link Projectile} from the ProjectileSource with an * initial velocity. + * <p> + * The family of launchProjectile methods only promise the ability to launch projectile types + * that the {@link ProjectileSource} is capable of firing in vanilla. + * Any other types of projectiles *may* be implemented but are not part of the method contract. * * @param <T> a projectile subclass * @param projectile class of the projectile to launch diff --git a/paper-api/src/main/java/org/bukkit/scoreboard/Objective.java b/paper-api/src/main/java/org/bukkit/scoreboard/Objective.java index d57634dd37..35755c9165 100644 --- a/paper-api/src/main/java/org/bukkit/scoreboard/Objective.java +++ b/paper-api/src/main/java/org/bukkit/scoreboard/Objective.java @@ -86,7 +86,7 @@ public interface Objective { * * @return true if scores are modifiable * @throws IllegalStateException if this objective has been unregistered - * @see Criterias#HEALTH + * @see Criteria#HEALTH */ boolean isModifiable(); diff --git a/paper-api/src/main/java/org/bukkit/scoreboard/Team.java b/paper-api/src/main/java/org/bukkit/scoreboard/Team.java index 284468fd3d..38deee00cf 100644 --- a/paper-api/src/main/java/org/bukkit/scoreboard/Team.java +++ b/paper-api/src/main/java/org/bukkit/scoreboard/Team.java @@ -265,7 +265,7 @@ public interface Team extends net.kyori.adventure.audience.ForwardingAudience { * Gets the Set of entries on the team * * @return entries on the team - * @throws IllegalStateException if this entries has been unregistered + * @throws IllegalStateException if this team has been unregistered */ @NotNull Set<String> getEntries(); diff --git a/paper-api/src/main/java/org/bukkit/util/BoundingBox.java b/paper-api/src/main/java/org/bukkit/util/BoundingBox.java index 9883983c33..5017b73bce 100644 --- a/paper-api/src/main/java/org/bukkit/util/BoundingBox.java +++ b/paper-api/src/main/java/org/bukkit/util/BoundingBox.java @@ -358,7 +358,7 @@ public class BoundingBox implements Cloneable, ConfigurationSerializable { * <p> * Negative values will shrink the bounding box in the corresponding * direction. Shrinking will be limited to the point where the affected - * opposite faces would meet if the they shrank at uniform speeds. + * opposite faces would meet if they shrank at uniform speeds. * * @param negativeX the amount of expansion in the negative x direction * @param negativeY the amount of expansion in the negative y direction diff --git a/paper-api/src/main/java/org/bukkit/util/CachedServerIcon.java b/paper-api/src/main/java/org/bukkit/util/CachedServerIcon.java index 612958a331..9a7768d412 100644 --- a/paper-api/src/main/java/org/bukkit/util/CachedServerIcon.java +++ b/paper-api/src/main/java/org/bukkit/util/CachedServerIcon.java @@ -5,7 +5,7 @@ import org.bukkit.event.server.ServerListPingEvent; import org.jetbrains.annotations.Nullable; /** - * This is a cached version of a server-icon. It's internal representation + * This is a cached version of a server-icon. Its internal representation * and implementation is undefined. * * @see Server#getServerIcon()