OpenSource/PaperMC
OpenSource/PaperMC
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2024-11-22 07:08:47 +01:00
Code Issues Projects Releases Packages Wiki Activity
PaperMC/patches/api/0056-Fix-upstream-javadocs.patch
Jake Potrebic ac554ad46d
Updated Upstream (Bukkit/CraftBukkit) (#10691) 
Updated Upstream (Bukkit/CraftBukkit)

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:
fa99e752 PR-1007: Add ItemMeta#getAsComponentString()
94a91782 Fix copy-pasted BlockType.Typed documentation
9b34ac8c Largely restore deprecated PotionData API
51a6449b PR-1008: Deprecate ITEMS_TOOLS, removed in 1.20.5
702d15fe Fix Javadoc reference
42f6cdf4 PR-919: Add internal ItemType and BlockType, delegate Material methods to them
237bb37b SPIGOT-1166, SPIGOT-7647: Expose Damager BlockState in EntityDamageByBlockEvent
035ea146 SPIGOT-6993: Allow #setVelocity to change the speed of a fireball and add a note to #setDirection about it
8c7880fb PR-1004: Improve field rename handling and centralize conversion between bukkit and string more
87c90e93 SPIGOT-7650: Add DamageSource for EntityDeathEvent and PlayerDeathEvent

CraftBukkit Changes:
4af0f22e8 SPIGOT-7664: Item meta should prevail over block states
c2ccc46ec SPIGOT-7666: Fix access to llama and horse special slot
124ac66d7 SPIGOT-7665: Fix ThrownPotion#getEffects() implementation only bringing custom effects
66f1f439a Restore null page behaviour of signed books even though not strictly allowed by API
6118e5398 Fix regression listening to minecraft:brand custom payloads
c1a26b366 Fix unnecessary and potential not thread-safe chat visibility check
12360a7ec Remove unused imports
147b098b4 PR-1397: Add ItemMeta#getAsComponentString()
428aefe0e Largely restore deprecated PotionData API
afe5b5ee9 PR-1275: Add internal ItemType and BlockType, delegate Material methods to them
8afeafa7d SPIGOT-1166, SPIGOT-7647: Expose Damager BlockState in EntityDamageByBlockEvent
4e7d749d4 SPIGOT-6993: Allow #setVelocity to change the speed of a fireball and add a note to #setDirection about it
441880757 Support both entity_data and bucket_entity_data on axolotl/fish buckets
0e22fdd1e Fix custom direct BlockState being not correctly set in DamageSource
f2182ed47 SPIGOT-7659: TropicalFishBucketMeta should use BUCKET_ENTITY_DATA
2a6207fe1 PR-1393: Improve field rename handling and centralize conversion between bukkit and string more
c024a5039 SPIGOT-7650: Add DamageSource for EntityDeathEvent and PlayerDeathEvent
741b84480 PR-1390: Improve internal handling of damage sources
0364df4e1 SPIGOT-7657: Error when loading angry entities
2024-05-11 23:48:37 +02:00

1580 lines
77 KiB
Diff
Raw Permalink 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 a04cde615f8c4bc593f8d9f8f6f1438008aaa707..548f6d28c28d74bed8b58ee82875909354afe132 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 6b3a332f556e7c49796a62f20fd33241bbcde09e..3b7087d5c71a498f513f67514db9e118780363c7 100644
--- a/src/main/java/org/bukkit/Bukkit.java
+++ b/src/main/java/org/bukkit/Bukkit.java
@@ -1506,6 +1506,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
*/
diff --git a/src/main/java/org/bukkit/ChunkSnapshot.java b/src/main/java/org/bukkit/ChunkSnapshot.java
index 0cf808356a1a5c6fc4bcf97a694ed9beb80a776a..dc765dea47a9a1c1520fb16ddb24f81413ed0dd1 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/Particle.java b/src/main/java/org/bukkit/Particle.java
index 3d636cb7f275df053d202356c5e9fad5b1112867..4a06ed9c769acb2eb4c6f4b76c84dc2e63176010 100644
--- a/src/main/java/org/bukkit/Particle.java
+++ b/src/main/java/org/bukkit/Particle.java
@@ -209,7 +209,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 9088bd9dfb515381d5df1c255ae3319f9cdde81e..012b5954a2f9dc61fb8ad29c4b8bce2648ddc681 100644
--- a/src/main/java/org/bukkit/Server.java
+++ b/src/main/java/org/bukkit/Server.java
@@ -570,13 +570,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);
@@ -1284,6 +1281,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
*/
diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
index 4dc687f16a8181876fb7b3e56b39a55ea5507408..98e3c12801cc36c868f08b15d1188295ea4364e0 100644
--- a/src/main/java/org/bukkit/World.java
+++ b/src/main/java/org/bukkit/World.java
@@ -2739,7 +2739,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
@@ -2773,7 +2773,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
@@ -2806,7 +2806,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/block/Bed.java b/src/main/java/org/bukkit/block/Bed.java
index f9bd74f9ce6bd6650726e5a993f9b6e292cdc74d..f4c37ce1fe7aac3dde8485ee51fc8888ed56e79e 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
-public interface Bed extends TileState, Colorable { }
+// Paper start
+// @Deprecated
+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 f8e12868f2e629cdf4784f0157fdb2f8e7b01f99..bda4ab21b3ac2acbe328c0c6887c33283399971e 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 be06f8db02ca41d5cc3a5dc02951ad27e3cc8f9d..d91a07c7bcb36b3810bb2db89afef1eefd89253d 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
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 91fc11dda99de506be83d40df8929bf7cd8e8d85..7dc631ebd009f5f5c3ac1699c3f3515c47609c05 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 a1615334cae50c7d64ca6d86cb7070405a26b332..e396f351a46e4220fa4df11eaa93d813dced664c 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/HumanEntity.java b/src/main/java/org/bukkit/entity/HumanEntity.java
index fffc478312566bc5c36dbacbdd86341d84d50054..8d97cf229ce1d14232d0342121b5db2230795a1d 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/Mob.java b/src/main/java/org/bukkit/entity/Mob.java
index 2926fa6071bc7640cc10280b5c3962b0ce7686f1..4f63988848443aff55619bc12ef12c925642a3f9 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 252390260f62ee945c21267cd8717b7725158a21..cd00d2a064ee4c86b394a7861182fba9cf79cfb3 100644
--- a/src/main/java/org/bukkit/entity/Player.java
+++ b/src/main/java/org/bukkit/entity/Player.java
@@ -478,15 +478,15 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
/**
* Saves the players current location, health, inventory, motion, and
- * other information into the username.dat file, in the world/player
- * 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 username.dat file, in the world/player
- * 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.
@@ -823,7 +823,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
@@ -1234,7 +1234,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)}
*/
@@ -1700,7 +1700,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
@@ -1727,7 +1727,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
@@ -1810,9 +1810,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>
@@ -1846,9 +1843,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>
@@ -1885,9 +1879,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..bfac874840cf1f36afba16ae4d176c5821a68cfb 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#GENERIC_MAX_HEALTH}</li>
+ * <li>{@link org.bukkit.attribute.Attribute#GENERIC_MOVEMENT_SPEED}</li>
+ * <li>{@link org.bukkit.attribute.Attribute#GENERIC_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 6bf3af3ed81b66f61e53105d3591165ea74dba0e..a91400cd8bb4c72d1f3200a17f6de025540fe09d 100644
--- a/src/main/java/org/bukkit/entity/Villager.java
+++ b/src/main/java/org/bukkit/entity/Villager.java
@@ -202,7 +202,7 @@ public interface Villager extends AbstractVillager {
*/
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.
*/
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 e534954457a9961a26dbec7ac035bec07e1d6694..a7c297364805c58ae16895055d8eae0484384b7d 100644
--- a/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java
@@ -13,6 +13,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();
@@ -29,6 +32,7 @@ public class BlockExplodeEvent extends BlockEvent implements Cancellable {
this.cancel = false;
}
+ @io.papermc.paper.annotation.DoNotUse // Paper
@Deprecated(forRemoval = true)
public BlockExplodeEvent(@NotNull final Block what, @NotNull final List<Block> blocks, final float yield) {
this(what, what.getState(), blocks, yield);
diff --git a/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java b/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java
index 340fa397e68c024df380a28db21545a0c83d9fa6..79ac8a5db689cf9f8e2ff4cb7c06df6989128d10 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 be0a2d1f234d8265d98e54e518a994957b1f3ab7..4e3c406ba883aae553e8d69b6b719b872cd6096c 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 fc2120e03737f5882d6ae916db93fdcf4939b2ba..f2edd4a9357832e9dec3fb0aafa006335d7b289b 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 e9de00e9e434d36117a672fa9fbfc7c52f284b67..4065432c884324b107d04f4ccd486085b0c440e7 100644
--- a/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java
+++ b/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java
@@ -154,11 +154,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 573165ddf3368a96e1ffc6476eb27c9e29a6f86e..148c4aad384ae8e3b8b22d264a84bddfbcafdf1e 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 10d0e18dfd423b108fe381e8142867eb10399359..099efafa14c10910e4ed04abb1823f0c1a96b6a6 100644
--- a/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java
@@ -9,7 +9,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 327876e0ad7dcfeb71d9d22afe1c04bcd71c3bf9..71d664dd89995f088c47d17b38547d530319470c 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 01c5e8b71338fbb4b1605e45bf2a2e705188f6b5..c9f395064656dd0126410eb3c6e197baa450c063 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,
@@ -238,7 +238,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 dee186e99463a56394bbc2039d1e763d109125b9..c6e4d69eecd2789b1d78fe99fe590932e9758ba1 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 020739697a0b535cad0b15b574f77cdabbdfa3eb..a965b6a78073c5da86ad671752eff4a270029420 100644
--- a/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java
@@ -7,7 +7,9 @@ import org.bukkit.event.block.BlockExpEvent;
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 79797a2be7fb139d528116d34d13e51d39b96e56..f2a2a2ad9930499c5bf624e73571a3294a90db14 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 6782024735a885ba0b1b4dba4a576740c1410366..8977f7609431c3c46324a82de84d4a32f4b71c57 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 HandlerList getHandlers() {
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 0cc6e29a5af28e95f87f415d6b2424d4622a6f34..c0b749a5bbf4980d01fed74768bb61909b579cb9 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 9adc827bc52eaa767a39c82e9cb0ff5a48e02b14..2dde946443fee1f6e79b882cbcb448549dc0c99c 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 f1918027c3a8735b31566856218611656b56db20..476fe14faa39f02444cab8ad95d4401033dc6938 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 05f1acaac3a49c42f6cf544adb3ffec267c72700..9f9c67e935940833bbfe58e6bfa398e6c86980d5 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.
@@ -44,8 +42,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)
*/
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 3d50775da447175b2a94ed9056ef36aa1e69c2eb..03839302c94adc3175d0a88065cd230257ffd20d 100644
--- a/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
+++ b/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
@@ -30,11 +30,8 @@ public class ShapelessRecipe extends CraftingRecipe {
* @param key the unique recipe key
* @param result The item you want the recipe to create.
* @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, result);
@@ -174,7 +171,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/ItemMeta.java b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
index a23d030d2204098be17d8b18021fd0bb79b4431b..f427334c6e875a13aa53052ac1b5a746186b4ffe 100644
--- a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
@@ -514,7 +514,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..7f9eabcaa4d803ee524a9cc8717379fe6a93a5af 100644
--- a/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java
@@ -8,8 +8,8 @@ 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}, or {@link Material#LEATHER_HORSE_ARMOR}) that can be colored.
*/
public interface LeatherArmorMeta extends ItemMeta {
diff --git a/src/main/java/org/bukkit/scoreboard/Objective.java b/src/main/java/org/bukkit/scoreboard/Objective.java
index 22b1dc5fd4d453161a5ee520072f8e8f955b3a80..a625bcab8e77b05b3341a52c708fae1542b7e3d5 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 52e8be769d2e9b69e9833bc9a7fe39afd10c5095..4d2b8e10263802432dfeac72666487f9547cd2c5 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