OpenSource/PaperMC
OpenSource/PaperMC
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2024-12-18 04:39:24 +01:00
Code Issues Projects Releases Packages Wiki Activity
PaperMC/patches/api/0053-Fix-upstream-javadocs.patch
Bjarne Koll da7138233f
Updated Upstream (Bukkit/CraftBukkit/Spigot) (#11702) 
Upstream has released updates that appear to apply and compile correctly.
This update has not been tested by PaperMC and as with ANY update, please do your own testing

Bukkit Changes:
ed0ec489 SPIGOT-7965: Unknown TransformReason for Hoglins
9db03457 SPIGOT-7964: Fix typo in Deprecation annotation
d14119af PR-1082: Add "since" to Deprecation annotations
e8a318d4 PR-1067: Add method to get Advancement requirements

CraftBukkit Changes:
40dd796db SPIGOT-7971: NotSerializableException on serialize CraftUseCooldownComponent
fa85c5e0a SPIGOT-7968: ProjectileHitEvent not trigerred when arrow hits entity
b75b792ec SPIGOT-7970: World#getMaxHeight() returning incorrect value
2b9a094bb SPIGOT-7965: Unknown TransformReason for Hoglins
fd3f5a380 SPIGOT-7966: Some trees do not generate with #generateTree
f2822317c PR-1515: Add a Class reader and Class node argument provider
07abf6852 PR-1514: Add a test case for ClassTraverser
a7577cb24 Fix Inventory#addItem not respecting max stack size
066a74e74 PR-1490: Add method to get Advancement requirements
4a1df30e4 PR-1512: Test Art class based on specific values instead of the implementation, to better catch implementation changes
53254c56f PR-1503: Simplify CAS loop to getAndSet
e9447dc5e Make BlockDataMeta#setBlockData hide unspecified states
dd08a7120 SPIGOT-7960: Fix inconsistency between natural item drop coordinates
e9e8ed753 SPIGOT-7960: Improve natural item drop methods

Spigot Changes:
60c9969b Rebuild patches
2024-12-03 15:47:48 +01:00

1869 lines
91 KiB
Diff
Raw Blame History

From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
From: Zach Brown <zach.brown@destroystokyo.com>
Date: Sat, 10 Jun 2017 16:59:40 -0500
Subject: [PATCH] Fix upstream javadocs
diff --git a/src/main/java/org/bukkit/BanList.java b/src/main/java/org/bukkit/BanList.java
index ac38b4af280cc7f52c70c238a6f4f9cccab1241d..5829aca9e5aa700bd95f19db3ae032100f74d5a3 100644
--- a/src/main/java/org/bukkit/BanList.java
+++ b/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/src/main/java/org/bukkit/Bukkit.java b/src/main/java/org/bukkit/Bukkit.java
index 29e13fd7c94c5c50e81b804e6dffc8721164f1d1..bacdb1742ecb98bb10651b0582500449bf904910 100644
--- a/src/main/java/org/bukkit/Bukkit.java
+++ b/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/src/main/java/org/bukkit/ChunkSnapshot.java b/src/main/java/org/bukkit/ChunkSnapshot.java
index 8832a2e0907299fb5f379b6938bbbc8e98688478..725d7944ce066ac56ed86b31628f00eb46cdcf64 100644
--- a/src/main/java/org/bukkit/ChunkSnapshot.java
+++ b/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/src/main/java/org/bukkit/HeightMap.java b/src/main/java/org/bukkit/HeightMap.java
index db6fcd635e295e561642d49941fd8e611247d38e..344b2b5d9207d2645bc5417d1ec00dd0a0b95604 100644
--- a/src/main/java/org/bukkit/HeightMap.java
+++ b/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/src/main/java/org/bukkit/Particle.java b/src/main/java/org/bukkit/Particle.java
index 13557f78a6853fdf0619f0479cab7591ddadf666..a1896780f312a91ab2330d2c850641d66143f23e 100644
--- a/src/main/java/org/bukkit/Particle.java
+++ b/src/main/java/org/bukkit/Particle.java
@@ -206,7 +206,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/src/main/java/org/bukkit/RegionAccessor.java b/src/main/java/org/bukkit/RegionAccessor.java
index 4c9fd558fbf7f57a948fbb7f80f4651048c0fb57..458119a9ef7ce8e1f59bd47caa5b4bc698715440 100644
--- a/src/main/java/org/bukkit/RegionAccessor.java
+++ b/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/src/main/java/org/bukkit/Server.java b/src/main/java/org/bukkit/Server.java
index 4225105fef7aee264b34d1687762b5fc8dccbc47..a506e618448c3bf4b56f54f8fe00d7158df29dd7 100644
--- a/src/main/java/org/bukkit/Server.java
+++ b/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/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
index e5d3ccf6e1bc87db1f5602214371c0e8ed4d5431..369e92f2b5e4b8fc7f5bf8a97058e827c91e4c59 100644
--- a/src/main/java/org/bukkit/World.java
+++ b/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/src/main/java/org/bukkit/attribute/AttributeModifier.java b/src/main/java/org/bukkit/attribute/AttributeModifier.java
index ecf3897bd2dbdeebfa09a00a692724a013b0186d..b90af00a8eb83d4c1b183fbc4f1e9eae84c9074b 100644
--- a/src/main/java/org/bukkit/attribute/AttributeModifier.java
+++ b/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/src/main/java/org/bukkit/block/Bed.java b/src/main/java/org/bukkit/block/Bed.java
index 20aaa7e15a71eef34ff4c06bad14464e7c9584dd..46778452893de3d8f1765994fb0c1ba62a90b315 100644
--- a/src/main/java/org/bukkit/block/Bed.java
+++ b/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/src/main/java/org/bukkit/block/Block.java b/src/main/java/org/bukkit/block/Block.java
index ab65d9769b73780dc126b4f11f2ad4528e6ab0c0..f440da5941e11c30145175cf24162e1ba2b4e3cf 100644
--- a/src/main/java/org/bukkit/block/Block.java
+++ b/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/src/main/java/org/bukkit/block/data/BlockData.java b/src/main/java/org/bukkit/block/data/BlockData.java
index 29fd06cb800f9b7cc91a120ccbe2980422ed9653..cd3b3e05cc825cfedec07f9a2a1e0b7b2a8866d6 100644
--- a/src/main/java/org/bukkit/block/data/BlockData.java
+++ b/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/src/main/java/org/bukkit/block/data/FaceAttachable.java b/src/main/java/org/bukkit/block/data/FaceAttachable.java
index 9599e1237b9717ddbf84c3738bf6c1293e8b3c54..950266b4bb0a2fabeb9539c5676ed58f0b0fe620 100644
--- a/src/main/java/org/bukkit/block/data/FaceAttachable.java
+++ b/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/src/main/java/org/bukkit/block/data/type/CommandBlock.java b/src/main/java/org/bukkit/block/data/type/CommandBlock.java
index 9a7122c907308e4e0a4d0eab815df16899503c19..3b1dab4c1c38477fbe651382f37fdb042ce67cd1 100644
--- a/src/main/java/org/bukkit/block/data/type/CommandBlock.java
+++ b/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/src/main/java/org/bukkit/block/data/type/Gate.java b/src/main/java/org/bukkit/block/data/type/Gate.java
index 494f97d47b52bc99b13748c1b57730fbd37d8f51..ebc98607b93294847f95e793304bc5d2528de2a3 100644
--- a/src/main/java/org/bukkit/block/data/type/Gate.java
+++ b/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/src/main/java/org/bukkit/block/data/type/Switch.java b/src/main/java/org/bukkit/block/data/type/Switch.java
index df8c2d60e7cce0294d3a1b1a6a81367a56602c26..16ced762f498b0dadd22789fa5d121d644bebf3d 100644
--- a/src/main/java/org/bukkit/block/data/type/Switch.java
+++ b/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/src/main/java/org/bukkit/entity/ArmorStand.java b/src/main/java/org/bukkit/entity/ArmorStand.java
index 6a1d563d1b7ea7e1060dfacfba98e4e1d4295790..c727b2d40efae8f08bdd159991afb8992568a58f 100644
--- a/src/main/java/org/bukkit/entity/ArmorStand.java
+++ b/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/src/main/java/org/bukkit/entity/Arrow.java b/src/main/java/org/bukkit/entity/Arrow.java
index a292579c9fa6eeac92fb1a21fa8144fbef307dad..38e6a8dbb248ead98cfb36bfb077d4e9e95b2c77 100644
--- a/src/main/java/org/bukkit/entity/Arrow.java
+++ b/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/src/main/java/org/bukkit/entity/EnderDragon.java b/src/main/java/org/bukkit/entity/EnderDragon.java
index 1e56aef9188487d3e9c737e85025f601ab359a72..92cd35c87bad578c2b714761c93a5b72ebf4bc9e 100644
--- a/src/main/java/org/bukkit/entity/EnderDragon.java
+++ b/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/src/main/java/org/bukkit/entity/Entity.java b/src/main/java/org/bukkit/entity/Entity.java
index 411297f66520774a4072c9e15aa9bdf03a527208..45d408f519767785b222c409170bbfecbd8d1931 100644
--- a/src/main/java/org/bukkit/entity/Entity.java
+++ b/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/src/main/java/org/bukkit/entity/HumanEntity.java b/src/main/java/org/bukkit/entity/HumanEntity.java
index b21f42e653553b6dbd571a1e8fba1e5a04f3bbd1..c90a0a00be78200adf217e2b3a8302b59af3cf7c 100644
--- a/src/main/java/org/bukkit/entity/HumanEntity.java
+++ b/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/src/main/java/org/bukkit/entity/ItemFrame.java b/src/main/java/org/bukkit/entity/ItemFrame.java
index b688b3856cb3068a539fcecfbfa113f8ab4160a9..c275b881cbd11307a6dcc7190d7a7d4063000ad8 100644
--- a/src/main/java/org/bukkit/entity/ItemFrame.java
+++ b/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/src/main/java/org/bukkit/entity/LivingEntity.java b/src/main/java/org/bukkit/entity/LivingEntity.java
index 598c88f02a764abe62f9f10833b2c499a0fb00ff..4b75a5e1ce788bc375d6147422e5bee6ef0c03be 100644
--- a/src/main/java/org/bukkit/entity/LivingEntity.java
+++ b/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/src/main/java/org/bukkit/entity/Mob.java b/src/main/java/org/bukkit/entity/Mob.java
index f3f62e13cc1b6172808c52f2d5f520f1f584e6db..ad5dbf310fe7b34c997bb339f09697222f862005 100644
--- a/src/main/java/org/bukkit/entity/Mob.java
+++ b/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/src/main/java/org/bukkit/entity/PigZombie.java b/src/main/java/org/bukkit/entity/PigZombie.java
index ae9eaaa8e38e1d9dfc459926c7fc51ddb89de84a..b2ec535bb1b0ce0c114ddd7638b90218b05cd835 100644
--- a/src/main/java/org/bukkit/entity/PigZombie.java
+++ b/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/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
index e014582d73fc821c0b6dcf19ae1f5dfdf510343c..5b12fa8c41a18ddfe08d82c138c0f71106c89d4d 100644
--- a/src/main/java/org/bukkit/entity/Player.java
+++ b/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 &lt;main
- * world&gt;/playerdata folder.
+ * other information into the &lt;uuid&gt;.dat file, in the
+ * &lt;level-name&gt;/playerdata/ folder.
*/
public void saveData();
/**
* Loads the players current location, health, inventory, motion, and
- * other information from the uuid.dat file, in the &lt;main
- * world&gt;/playerdata folder.
+ * other information from the &lt;uuid&gt;.dat file, in the
+ * &lt;level-name&gt;/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 '&amp;'
* @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/src/main/java/org/bukkit/entity/Slime.java b/src/main/java/org/bukkit/entity/Slime.java
index a5ad3250cebfeb302c58e0bfd6db1295913c927e..0a2d603bf6a3f60d3fa7d85df6ef2373fc93d848 100644
--- a/src/main/java/org/bukkit/entity/Slime.java
+++ b/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/src/main/java/org/bukkit/entity/Sniffer.java b/src/main/java/org/bukkit/entity/Sniffer.java
index af5110b4160979c39cc1e5de6fa3bd7957b21403..15a0a733b0e5804655b5957cbf20831290d52a08 100644
--- a/src/main/java/org/bukkit/entity/Sniffer.java
+++ b/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/src/main/java/org/bukkit/entity/Villager.java b/src/main/java/org/bukkit/entity/Villager.java
index c48f13cc8ece0fa9913450e4402e496ce01a03fb..af4582f3e4687933dac6ccd43667a373f8daedb6 100644
--- a/src/main/java/org/bukkit/entity/Villager.java
+++ b/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/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java b/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java
index a0f6f1af304190b4c5db4b284d460f625eeb7801..7e21548cac8515c281ec86853e9272ab7695b24f 100644
--- a/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java
+++ b/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/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java b/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java
index 1df172c0bb48de3b143179a3f0c63d6ecc30649e..254d549f956053af4264ca3a52d34a97ede4273d 100644
--- a/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java
+++ b/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/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java b/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java
index 0392cc3a00f77a11608bf78cc157a411c7bcd976..23b3f44ab009bd49dac60a4045f12858f12cb2ba 100644
--- a/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java
+++ b/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/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java b/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java
index 77215c1dd2419104607138c45666ce0d84866670..3bfd0f6edc44d6503988f3c3c7a267f1be2986e3 100644
--- a/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java
+++ b/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/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
index a722e090e788f5497569e69137923682e2abcbac..4c8f388897ff9ddd077695172622c5550651858b 100644
--- a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
+++ b/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/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java b/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java
index a37febd0d4dd5b733e9ee72628fdf9395fec4367..9cee218b9ee14688356f16b1f58512186286e7e9 100644
--- a/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java
+++ b/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/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java b/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java
index c746c2e73ab9c91376ceaeab43423edb8009fe1a..5d2597378d36ccace672db0768267d3499100cf1 100644
--- a/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java
+++ b/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/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java b/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java
index 0a3699226be1941c0ad1ff1ad8f80bad3aec42aa..971093bd2500543e680db1c92f781bfd5c35dd83 100644
--- a/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java
+++ b/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/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java b/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java
index fc2158793aec67310bc8d06ac1f0bac39d2a5c3d..50161d313cfcc9e61441589685c3d0e1f057dd86 100644
--- a/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java
+++ b/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/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java b/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java
index c866df03d66dd8724e12c7353da4cf144c70b2c8..94ee5a3354722aa5d825da727b7b7071fdc6bacc 100644
--- a/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java
+++ b/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/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java b/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java
index 4f116956071148a1a148b94ceb4654d3934e2f7f..a7bd15d51a4ff9142cfb341f65050a88b5f5fa8d 100644
--- a/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java
+++ b/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/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java b/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java
index 31a5515c08c9454d52a0d946d103a2d526c15e48..d743cc5ee34fd7bc5db92f4b17fed9f3aa5ffbcc 100644
--- a/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java
+++ b/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/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java b/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java
index d51d2ec1d04d9ea8a25a70d0d856f2355ebfcb4a..7ecff9fcee19fc94be784474fea620e5dd434731 100644
--- a/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java
+++ b/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/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java b/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java
index 842cfd3e9829c61250e98d1a45602a81549de176..808142232a722cb6466bac78d00dc55c18ebe109 100644
--- a/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java
+++ b/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/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java b/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java
index c17ff41a688b2cbd877cda25d4ec033ac8ef5524..bd67b7cba78b9bbdd82a5a40048e658a979e3108 100644
--- a/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java
+++ b/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/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java b/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java
index bc71bc2d3ace0d19d730c09f05f9e0655bcee8f5..24077da8e6a7937f66eafc6779206055cf82e8d2 100644
--- a/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java
+++ b/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/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java b/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java
index 65db4991bd4789991868c0d75fea4034fed487a8..5ffd28fd24b4477a07fc9f6a3f669a6f4da9fa26 100644
--- a/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java
+++ b/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/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java b/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java
index 066e7dd9a34d35c8b643a5efcf95d6a5ef47c7ee..f8f9b08a0bd82a2667ae4e0c99dae9103f0db3f0 100644
--- a/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java
+++ b/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/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java b/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java
index 1440c6115520d692faf75455df35b92aa8734491..0808e7aeffb69160913344de5b5e21d5e857f1d6 100644
--- a/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java
+++ b/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/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java b/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
index e1f0ae392c14b940581ed966da42a58ec5cb005d..5832c610e4fad1372e70dc01bd04ba684a89b492 100644
--- a/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
+++ b/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/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java b/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java
index 5861247c1b8ee4fe2736fd5098e05a2ca9ab78ea..c0cc82d98348e8aae3cb56bafb2fcb590b03094f 100644
--- a/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java
+++ b/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/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java b/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java
index 9013d043503d175004ad276799e5935b7fa59dc4..ceae092eb782698803c6c3df41267dde20ba62b2 100644
--- a/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java
+++ b/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/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java b/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java
index 08a7c564fe5d3d232998d1789d4d4723a59c1430..8a5be3f0322ac19aeac3f00df54add0e73bc87ed 100644
--- a/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java
+++ b/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/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java b/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java
index c3eb020498121746ac0650522b15f1346bbca5fa..9eb2c2a1fe385d306df8e44476339073a7532f60 100644
--- a/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java
+++ b/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/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java b/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java
index e4c32b21ab013703a6a1b07a1ad564d914ebe83f..e58fecf0fe54db06e0e944027923a352fd8005d8 100644
--- a/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java
+++ b/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/src/main/java/org/bukkit/generator/ChunkGenerator.java b/src/main/java/org/bukkit/generator/ChunkGenerator.java
index 4b952b0178de24e0902b48dfceff99ef1c926e43..b4dab4cf521c7fb067e88d985572f12d14a2c8df 100644
--- a/src/main/java/org/bukkit/generator/ChunkGenerator.java
+++ b/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/src/main/java/org/bukkit/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java
index 37298cec0234b6c681d912791c1235fbfc427d93..720038083f8c8ab1f29ac424f2d9dbb5cbc8b533 100644
--- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
+++ b/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/src/main/java/org/bukkit/inventory/ItemFlag.java b/src/main/java/org/bukkit/inventory/ItemFlag.java
index 8453bd058d426c1088b04c55d2448d205f0a104b..1b3580d1861af402396121805715e4087b3bc587 100644
--- a/src/main/java/org/bukkit/inventory/ItemFlag.java
+++ b/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/src/main/java/org/bukkit/inventory/PlayerInventory.java b/src/main/java/org/bukkit/inventory/PlayerInventory.java
index 6933fb24ea3e6c2e306a69407ae7fa280101419a..b1f4b8f2666e8012eb8a1e21a2b958fe6e03f74f 100644
--- a/src/main/java/org/bukkit/inventory/PlayerInventory.java
+++ b/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/src/main/java/org/bukkit/inventory/ShapedRecipe.java b/src/main/java/org/bukkit/inventory/ShapedRecipe.java
index 83b08fa8a42b07a9abc84f30df921a5c2a60adbf..64916d17ee81cf2eaec7fbac1cb071db3b3eb258 100644
--- a/src/main/java/org/bukkit/inventory/ShapedRecipe.java
+++ b/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/src/main/java/org/bukkit/inventory/ShapelessRecipe.java b/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
index 969710cc69fe4c1265f509915cd6bf78d47a2d78..354af775093fd3a74dac6c64244d8f3464397f72 100644
--- a/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
+++ b/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/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java b/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
index 07c3dff4d6190ef388d9c1e1c36f67f00a3e8e66..597a18a767b68b47e81454b7d44613c7178c1366 100644
--- a/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
+++ b/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/src/main/java/org/bukkit/inventory/meta/BlockStateMeta.java b/src/main/java/org/bukkit/inventory/meta/BlockStateMeta.java
index e7d905b1146b2bdd2da5bdeb6bf3541fb181d59e..c7d3041221742f6655155f19ef2addcaf2401015 100644
--- a/src/main/java/org/bukkit/inventory/meta/BlockStateMeta.java
+++ b/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/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java b/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java
index 35c6594fd1040a1af1029e7260e5e3a9307b107d..d58719ee75bef8bc265bfc81bc5d88a426e01dd9 100644
--- a/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java
+++ b/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/src/main/java/org/bukkit/inventory/meta/ItemMeta.java b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
index f83ec1c5ddce1a35b1c164b988f7fc6b9c310322..c81465e35808135329495fc4669d5616421451b7 100644
--- a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
@@ -744,7 +744,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
@@ -753,7 +753,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
JukeboxPlayableComponent getJukeboxPlayable();
/**
- * Sets the item tool.
+ * Sets the jukebox playable component.
*
* @param jukeboxPlayable new component
*/
@@ -780,7 +780,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/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java b/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java
index c1676991c3cc5f8d6e3f97d8cb356d6e2aa52809..c701d5fbc5fef503f18a3a46fa54c983bf96e895 100644
--- a/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java
+++ b/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/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java b/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java
index 43f0df04f3cdff7d7db73321a2886f3a737e3c9f..5c741228b2338a7c4de2fe736eb789511abf4880 100644
--- a/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java
+++ b/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/src/main/java/org/bukkit/inventory/meta/components/UseCooldownComponent.java b/src/main/java/org/bukkit/inventory/meta/components/UseCooldownComponent.java
index 4086a413895f82b51bf192ceffdfee4a939c6fed..172032e56ee8e4e1b13ec6b41a5122a33b18bc64 100644
--- a/src/main/java/org/bukkit/inventory/meta/components/UseCooldownComponent.java
+++ b/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/src/main/java/org/bukkit/plugin/Plugin.java b/src/main/java/org/bukkit/plugin/Plugin.java
index 8c76716249e44ed8bf6be94c1f5c7b6d9bb35be2..68a0ed5f0ed25e98f4ab4d1e482ec2ccfda9cd3a 100644
--- a/src/main/java/org/bukkit/plugin/Plugin.java
+++ b/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/src/main/java/org/bukkit/plugin/java/JavaPlugin.java b/src/main/java/org/bukkit/plugin/java/JavaPlugin.java
index 2a14522c484febcd880d00197df4359a0020dddd..7f17337b9f0fb60fa1c91c47af496c03290d1b1c 100644
--- a/src/main/java/org/bukkit/plugin/java/JavaPlugin.java
+++ b/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/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java b/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java
index b84b37fe27d84574dc5897285f1d9a1437bd322c..281ae60a6be7e39aab4f27b4c7de3d49ada9a557 100644
--- a/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java
+++ b/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/src/main/java/org/bukkit/projectiles/ProjectileSource.java b/src/main/java/org/bukkit/projectiles/ProjectileSource.java
index eabd8b926ec1c934cd7e77b7cc6adfae16771021..8557bfefaf02538dec95adb29734ae2cf50f3f8c 100644
--- a/src/main/java/org/bukkit/projectiles/ProjectileSource.java
+++ b/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/src/main/java/org/bukkit/scoreboard/Objective.java b/src/main/java/org/bukkit/scoreboard/Objective.java
index d57634dd3796a695aba7623d2b04e35d630887b3..35755c9165c1b48eaacfff86a50a7973476fe04b 100644
--- a/src/main/java/org/bukkit/scoreboard/Objective.java
+++ b/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/src/main/java/org/bukkit/scoreboard/Team.java b/src/main/java/org/bukkit/scoreboard/Team.java
index 284468fd3d310a7acdffa31f0f6593f5a98419ba..38deee00cfe2f6803070e98cd9ded95d859bf8e1 100644
--- a/src/main/java/org/bukkit/scoreboard/Team.java
+++ b/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/src/main/java/org/bukkit/util/BoundingBox.java b/src/main/java/org/bukkit/util/BoundingBox.java
index 9883983c33fcff0f4c1e23867adafa436e2ed96f..5017b73bcec0d4d5256d89db14201c03829dc981 100644
--- a/src/main/java/org/bukkit/util/BoundingBox.java
+++ b/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/src/main/java/org/bukkit/util/CachedServerIcon.java b/src/main/java/org/bukkit/util/CachedServerIcon.java
index 612958a331575d1da2715531ebdf6b1168f2e860..9a7768d41270714d4a1c89b4dcb436cc66f57545 100644
--- a/src/main/java/org/bukkit/util/CachedServerIcon.java
+++ b/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()
Reference in a new issue View git blame Copy permalink