From 67275a04a74e8b9e32b99fc45cbba5759fdcc626 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)

---
 .../api/Fix-Spigot-annotation-mistakes.patch  |  25 ++
 patches/api/Fix-upstream-javadocs.patch       | 250 +++++++++++++++++-
 ...t-set-drop-chance-to-EntityEquipment.patch |   2 +-
 3 files changed, 267 insertions(+), 10 deletions(-)

diff --git a/patches/api/Fix-Spigot-annotation-mistakes.patch b/patches/api/Fix-Spigot-annotation-mistakes.patch
index b9bbe2e621..5321f7cd61 100644
--- a/patches/api/Fix-Spigot-annotation-mistakes.patch
+++ b/patches/api/Fix-Spigot-annotation-mistakes.patch
@@ -408,6 +408,19 @@ index 0000000000000000000000000000000000000000..00000000000000000000000000000000
  @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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
+--- a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
++++ b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
+@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
 --- a/src/main/java/org/bukkit/event/player/PlayerShowEntityEvent.java
@@ -481,6 +494,18 @@ index 0000000000000000000000000000000000000000..00000000000000000000000000000000
  
      /**
       * 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
+--- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
++++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
+@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
 --- a/src/main/java/org/bukkit/inventory/FurnaceRecipe.java
diff --git a/patches/api/Fix-upstream-javadocs.patch b/patches/api/Fix-upstream-javadocs.patch
index 7ab38ff374..9b90257459 100644
--- a/patches/api/Fix-upstream-javadocs.patch
+++ b/patches/api/Fix-upstream-javadocs.patch
@@ -124,16 +124,248 @@ index 0000000000000000000000000000000000000000..00000000000000000000000000000000
       * @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
+diff --git a/src/main/java/org/bukkit/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java
 index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
---- a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
-+++ b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
-@@ -0,0 +0,0 @@ public class PlayerMoveEvent extends PlayerEvent implements Cancellable {
+--- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
++++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
+@@ -0,0 +0,0 @@ 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
+@@ -0,0 +0,0 @@ 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
+@@ -0,0 +0,0 @@ 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()
+@@ -0,0 +0,0 @@ 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();
+ 
+     /**
+@@ -0,0 +0,0 @@ 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();
+ 
+     /**
+@@ -0,0 +0,0 @@ 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();
+ 
+     /**
+@@ -0,0 +0,0 @@ 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();
+ 
+     /**
+@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
+--- a/src/main/java/org/bukkit/inventory/PlayerInventory.java
++++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java
+@@ -0,0 +0,0 @@ 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
+@@ -0,0 +0,0 @@ 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
+@@ -0,0 +0,0 @@ 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/add-get-set-drop-chance-to-EntityEquipment.patch b/patches/api/add-get-set-drop-chance-to-EntityEquipment.patch
index b660e57286..688074e1c3 100644
--- a/patches/api/add-get-set-drop-chance-to-EntityEquipment.patch
+++ b/patches/api/add-get-set-drop-chance-to-EntityEquipment.patch
@@ -10,7 +10,7 @@ index 0000000000000000000000000000000000000000..00000000000000000000000000000000
 +++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
 @@ -0,0 +0,0 @@ public interface EntityEquipment {
       */
-     @Nullable
+     @NotNull // Paper
      Entity getHolder();
 +    // Paper start
 +    /**