From 3f7111d4e12c57991eca10161a36827890602c0d Mon Sep 17 00:00:00 2001
From: Jake Potrebic <jake.m.potrebic@gmail.com>
Date: Tue, 31 May 2022 13:40:21 -0700
Subject: [PATCH] Fix EntityEquipment and related javadocs (#7380)

---
 patches/api/0054-Fix-upstream-javadocs.patch  | 252 +++++++++++++++++-
 .../0175-Fix-Spigot-annotation-mistakes.patch |  27 +-
 ...t-set-drop-chance-to-EntityEquipment.patch |   6 +-
 3 files changed, 271 insertions(+), 14 deletions(-)

diff --git a/patches/api/0054-Fix-upstream-javadocs.patch b/patches/api/0054-Fix-upstream-javadocs.patch
index 33fefd3c7..8d3eb7cc4 100644
--- a/patches/api/0054-Fix-upstream-javadocs.patch
+++ b/patches/api/0054-Fix-upstream-javadocs.patch
@@ -124,16 +124,248 @@ index 1119e26e270bb45f517955b19d95a9ec3d113634..4631647c64c89ffdde2d9b63bdab974a
       * @param sz The new size of the slime.
       */
      public void setSize(int sz);
-diff --git a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
-index 1b2267f4e8ebded198773ec80e2bff2c861c7084..1a58734d919fae247eeb85dd785fd59990856505 100644
---- a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
-+++ b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
-@@ -78,7 +78,7 @@ public class PlayerMoveEvent extends PlayerEvent implements Cancellable {
+diff --git a/src/main/java/org/bukkit/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java
+index d5b50a4a954fed35d37f03f1a277cc173ca106df..a91fa5386afd7a1137adb921ad5adb798604772f 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.
       *
-      * @return Location the player moved to
++     * <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.getItemInHand(); // will return a mirror
++     * } else {
++     *     equipment.getItemInHand(); // will return a copy
++     * }
++     * }</pre>
+      *
+      * @return The helmet being worn
       */
 -    @Nullable
-+    @NotNull // Paper
-     public Location getTo() {
-         return to;
-     }
++    @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();
+ 
+     /**
+@@ -202,12 +296,25 @@ public interface EntityEquipment {
+     void setBoots(@Nullable ItemStack boots, boolean silent);
+ 
+     /**
+-     * Gets a copy of all worn armor
++     * Gets all worn armor
++     *
++     * <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 The array of worn armor. Individual items may be null.
+      */
+-    @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
+diff --git a/src/main/java/org/bukkit/inventory/PlayerInventory.java b/src/main/java/org/bukkit/inventory/PlayerInventory.java
+index 62fbd7f6d8195bebcab7f704a0a485a1bbeca26c..5461f7fa75f5a065bb333b4a113640b5fe1e3825 100644
+--- a/src/main/java/org/bukkit/inventory/PlayerInventory.java
++++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java
+@@ -158,7 +158,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
+@@ -174,7 +174,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
+@@ -190,7 +190,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/patches/api/0175-Fix-Spigot-annotation-mistakes.patch b/patches/api/0175-Fix-Spigot-annotation-mistakes.patch
index 99f6ed7ac..9b1bba2fb 100644
--- a/patches/api/0175-Fix-Spigot-annotation-mistakes.patch
+++ b/patches/api/0175-Fix-Spigot-annotation-mistakes.patch
@@ -408,6 +408,19 @@ index d8a73cd22268e90eb438f522b9019f826f343275..78869fdb9cf4c541dff7d67b51866914
  @Warning(false)
  public class PlayerHideEntityEvent extends PlayerEvent {
  
+diff --git a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
+index 1b2267f4e8ebded198773ec80e2bff2c861c7084..1a58734d919fae247eeb85dd785fd59990856505 100644
+--- a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
++++ b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
+@@ -78,7 +78,7 @@ public class PlayerMoveEvent extends PlayerEvent implements Cancellable {
+      *
+      * @return Location the player moved to
+      */
+-    @Nullable
++    @NotNull // Paper
+     public Location getTo() {
+         return to;
+     }
 diff --git a/src/main/java/org/bukkit/event/player/PlayerShowEntityEvent.java b/src/main/java/org/bukkit/event/player/PlayerShowEntityEvent.java
 index 5408a8c123942a56ef11597ae6cdb77e14f741e3..29bb84145be18ef9162abdfc8820f2b3f7fd0db5 100644
 --- a/src/main/java/org/bukkit/event/player/PlayerShowEntityEvent.java
@@ -481,6 +494,18 @@ index df81bac9ecff697f98941e5c8490e10391e90090..a32977ba3ba60a1c9aee6e469d5d6cd1
  
      /**
       * Get the current recipe formed on the crafting inventory, if any.
+diff --git a/src/main/java/org/bukkit/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java
+index a91fa5386afd7a1137adb921ad5adb798604772f..42f76751ec414648ee719c341d471d947bf85be6 100644
+--- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
++++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
+@@ -511,6 +511,6 @@ public interface EntityEquipment {
+      *
+      * @return the entity this EntityEquipment belongs to
+      */
+-    @Nullable
++    @NotNull // Paper
+     Entity getHolder();
+ }
 diff --git a/src/main/java/org/bukkit/inventory/FurnaceRecipe.java b/src/main/java/org/bukkit/inventory/FurnaceRecipe.java
 index 1d442dc16cbb0fed21714d47007f3f11e30c57d4..af8f7b88edf0fa790edcf16356a030c4834f531e 100644
 --- a/src/main/java/org/bukkit/inventory/FurnaceRecipe.java
@@ -602,7 +627,7 @@ index 487e6a6391123a4792c3bdeba869aa2bcb5922cc..46bf24aed3e959d216d94603560cb75a
          return this.meta == null ? Bukkit.getItemFactory().getItemMeta(this.type) : this.meta.clone();
      }
 diff --git a/src/main/java/org/bukkit/inventory/PlayerInventory.java b/src/main/java/org/bukkit/inventory/PlayerInventory.java
-index 62fbd7f6d8195bebcab7f704a0a485a1bbeca26c..8b5385e39f64c4df8e235a8832d91e55642421ce 100644
+index 5461f7fa75f5a065bb333b4a113640b5fe1e3825..c4d657727e508cb941320730a9d3aa5486712ef3 100644
 --- a/src/main/java/org/bukkit/inventory/PlayerInventory.java
 +++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java
 @@ -14,8 +14,7 @@ public interface PlayerInventory extends Inventory {
diff --git a/patches/api/0282-add-get-set-drop-chance-to-EntityEquipment.patch b/patches/api/0282-add-get-set-drop-chance-to-EntityEquipment.patch
index 83995d7a9..1cdb558cb 100644
--- a/patches/api/0282-add-get-set-drop-chance-to-EntityEquipment.patch
+++ b/patches/api/0282-add-get-set-drop-chance-to-EntityEquipment.patch
@@ -5,12 +5,12 @@ Subject: [PATCH] add get-set drop chance to EntityEquipment
 
 
 diff --git a/src/main/java/org/bukkit/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java
-index d5b50a4a954fed35d37f03f1a277cc173ca106df..3f2f5beadfd6df0aaab5853783001ec2cca7a819 100644
+index ac9e606b85e0715b7e1b331a987c0ee34ee541ff..7b21e913a3ac9beb5dab91f11b1a0aa62e33ad36 100644
 --- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
 +++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
-@@ -406,4 +406,32 @@ public interface EntityEquipment {
+@@ -513,4 +513,32 @@ public interface EntityEquipment {
       */
-     @Nullable
+     @NotNull // Paper
      Entity getHolder();
 +    // Paper start
 +    /**