[ci skip] Fix incorrect documentation for BlockDropItemEvent (#10175)

Co-authored-by: Bjarne Koll <[email protected]>

2 files changed, 29 insertions, 2 deletions

diff --git a/patches/api/0056-Fix-upstream-javadocs.patch b/patches/api/0056-Fix-upstream-javadocs.patch
index 72c05a4434..93c118684d 100644
--- a/patches/api/0056-Fix-upstream-javadocs.patch
+++ b/patches/api/0056-Fix-upstream-javadocs.patch
@@ -572,6 +572,33 @@ index 6bf3af3ed81b66f61e53105d3591165ea74dba0e..a91400cd8bb4c72d1f3200a17f6de025
           * 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 44f7f6939a27b9a0a796d91eac4b7c97ec90a643..641c71ab66bd2499b35cf3c1d533fd105d096e10 100644
 --- a/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java
diff --git a/patches/api/0255-Allow-adding-items-to-BlockDropItemEvent.patch b/patches/api/0255-Allow-adding-items-to-BlockDropItemEvent.patch
index 984da00f52..c6b7565fe4 100644
--- a/patches/api/0255-Allow-adding-items-to-BlockDropItemEvent.patch
+++ b/patches/api/0255-Allow-adding-items-to-BlockDropItemEvent.patch
@@ -5,10 +5,10 @@ Subject: [PATCH] Allow adding items to BlockDropItemEvent
 
 
 diff --git a/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java b/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java
-index a0f6f1af304190b4c5db4b284d460f625eeb7801..3dd4bd38e72c04e74e5787fb38ca9abd10bad06b 100644
+index 7e21548cac8515c281ec86853e9272ab7695b24f..4c5ee91de162b202c2db8bf68259ad41a430125d 100644
 --- a/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java
 +++ b/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java
-@@ -64,7 +64,7 @@ public class BlockDropItemEvent extends BlockEvent implements Cancellable {
+@@ -68,7 +68,7 @@ public class BlockDropItemEvent extends BlockEvent implements Cancellable {
       * Gets list of the Item drops caused by the block break.
       *
       * This list is mutable - removing an item from it will cause it to not