[ci skip] Fix inventorycloseevent javadocs (#9533)

* Add InventoryCloseEvent safety doc comment, similar to InventoryClickEvent

* Fix inventorycloseevent javadocs

* Fix InventoryCloseEvent and InventoryClickEvent javadocs

* remove extra +

---------

Co-authored-by: Jake Potrebic <jake.m.potrebic@gmail.com>

patches/api/0055-Fix-upstream-javadocs.patch

@@ -3,7 +3,6 @@ From: Zach Brown <zach.brown@destroystokyo.com>
 Date: Sat, 10 Jun 2017 16:59:40 -0500
 Subject: [PATCH] Fix upstream javadocs
 
-Upstream still refuses to use Java 8 with the API so they are likely unaware these are even issues.
 
 diff --git a/src/main/java/org/bukkit/BanList.java b/src/main/java/org/bukkit/BanList.java
 index ce35cf91d4a5156e08cd5100fd65db28e38c30e6..c229d3bc37c4e454a4b5a93eda1fe6466a4f4e8b 100644
@@ -680,10 +679,24 @@ index c17ff41a688b2cbd877cda25d4ec033ac8ef5524..bd67b7cba78b9bbdd82a5a40048e658a
  public class PiglinBarterEvent extends EntityEvent implements Cancellable {
 
 diff --git a/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java b/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
-index 79797a2be7fb139d528116d34d13e51d39b96e56..0921484e921dbd200725b9298f655720618b5362 100644
+index 79797a2be7fb139d528116d34d13e51d39b96e56..fe58058f9b5d29388d48115cc81dc48ab08c58c1 100644
 --- a/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
 +++ b/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
-@@ -92,7 +92,7 @@ public class InventoryClickEvent extends InventoryInteractEvent {
+@@ -19,9 +19,10 @@ import org.jetbrains.annotations.Nullable;
+  * 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 +93,7 @@ public class InventoryClickEvent extends InventoryInteractEvent {
      /**
       * Gets the ItemStack currently in the clicked slot.
       *
@@ -692,6 +705,38 @@ index 79797a2be7fb139d528116d34d13e51d39b96e56..0921484e921dbd200725b9298f655720
       */
      @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

patches/api/0119-InventoryCloseEvent-Reason-API.patch

@@ -27,10 +27,10 @@ index 9e012c3c0671e5d0e55c243fdb4e14057038c153..d44c5a3fda0b159dc541246cb2fca842
       * Returns the ItemStack currently in your hand, can be empty.
       *
 diff --git a/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java b/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java
-index 5861247c1b8ee4fe2736fd5098e05a2ca9ab78ea..21ad8888c0e403bfc63518502577d651c02dda05 100644
+index 3cf2e2e87b8021f4c5e046b22ed89798b4172ae7..d527e3d7ba8d5b8c044e5a04ebdb9a2c117f22c7 100644
 --- a/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java
 +++ b/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java
-@@ -11,9 +11,60 @@ import org.jetbrains.annotations.NotNull;
+@@ -30,9 +30,60 @@ import org.jetbrains.annotations.NotNull;
   */
  public class InventoryCloseEvent extends InventoryEvent {
      private static final HandlerList handlers = new HandlerList();