[ci skip] clarify javadocs for Block#getDrops (#10153)

5 files changed, 46 insertions, 6 deletions

diff --git a/patches/api/0056-Fix-upstream-javadocs.patch b/patches/api/0056-Fix-upstream-javadocs.patch
index bb48849265..72c05a4434 100644
--- a/patches/api/0056-Fix-upstream-javadocs.patch
+++ b/patches/api/0056-Fix-upstream-javadocs.patch
@@ -203,7 +203,7 @@ index f9bd74f9ce6bd6650726e5a993f9b6e292cdc74d..f4c37ce1fe7aac3dde8485ee51fc8888
 +// Paper end
 +}
 diff --git a/src/main/java/org/bukkit/block/Block.java b/src/main/java/org/bukkit/block/Block.java
-index f8e12868f2e629cdf4784f0157fdb2f8e7b01f99..870ad6cd930653e6248abcc0fce94ffafbe9ebde 100644
+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 {
@@ -215,6 +215,46 @@ index f8e12868f2e629cdf4784f0157fdb2f8e7b01f99..870ad6cd930653e6248abcc0fce94ffa
       *
       * @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
diff --git a/patches/api/0173-Fix-Spigot-annotation-mistakes.patch b/patches/api/0173-Fix-Spigot-annotation-mistakes.patch
index 9de5c35b3e..9b652d1d0d 100644
--- a/patches/api/0173-Fix-Spigot-annotation-mistakes.patch
+++ b/patches/api/0173-Fix-Spigot-annotation-mistakes.patch
@@ -662,7 +662,7 @@ diff --git a/src/main/java/org/bukkit/block/Block.java b/src/main/java/org/bukki
 index f3a18e337a579b602b1289bccdf454334a663fcf..c22f333174bd6b8860ee06a71f713e4be8fa64ec 100644
 --- a/src/main/java/org/bukkit/block/Block.java
 +++ b/src/main/java/org/bukkit/block/Block.java
-@@ -517,7 +517,7 @@ public interface Block extends Metadatable, Translatable {
+@@ -526,7 +526,7 @@ public interface Block extends Metadatable, Translatable {
       * @return a list of dropped items for this type of block
       */
      @NotNull
diff --git a/patches/api/0178-Add-BlockSoundGroup-interface.patch b/patches/api/0178-Add-BlockSoundGroup-interface.patch
index dd3fc87e20..34ee41dfd3 100644
--- a/patches/api/0178-Add-BlockSoundGroup-interface.patch
+++ b/patches/api/0178-Add-BlockSoundGroup-interface.patch
@@ -76,10 +76,10 @@ index 0000000000000000000000000000000000000000..ec36942128cbacae171584c89480b4aa
 +    Sound getFallSound();
 +}
 diff --git a/src/main/java/org/bukkit/block/Block.java b/src/main/java/org/bukkit/block/Block.java
-index 653a83b7ceb5cec1d92aed5250ae50e714fe5f9f..2b267d4c9adcc13722d4a655a98ca16a0f9746ca 100644
+index da03d5964f5f007ab338980cbb67e4335b1ae4b4..2011858eb3edeab1516198021436c3df294a8ab4 100644
 --- a/src/main/java/org/bukkit/block/Block.java
 +++ b/src/main/java/org/bukkit/block/Block.java
-@@ -607,4 +607,25 @@ public interface Block extends Metadatable, Translatable {
+@@ -616,4 +616,25 @@ public interface Block extends Metadatable, Translatable {
       * @return <code>true</code> if the block data can be placed here
       */
      boolean canPlace(@NotNull BlockData data);
diff --git a/patches/api/0212-Add-methods-to-get-translation-keys.patch b/patches/api/0212-Add-methods-to-get-translation-keys.patch
index 41c5b876fc..f203ee5d2c 100644
--- a/patches/api/0212-Add-methods-to-get-translation-keys.patch
+++ b/patches/api/0212-Add-methods-to-get-translation-keys.patch
@@ -294,7 +294,7 @@ index a7c58adb6404e04a673bf91d491d7fef56dc890e..85a5e9a3b41798cb3cb6687ed379a5e3
  
      /**
       * Gets the metadata for this block
-@@ -673,5 +673,12 @@ public interface Block extends Metadatable, Translatable {
+@@ -682,5 +682,12 @@ public interface Block extends Metadatable, Translatable {
       * @return the sound group for this block
       */
      @NotNull org.bukkit.SoundGroup getBlockSoundGroup();
diff --git a/patches/api/0224-Add-Destroy-Speed-API.patch b/patches/api/0224-Add-Destroy-Speed-API.patch
index 4bdd3a3889..d3bcb47524 100644
--- a/patches/api/0224-Add-Destroy-Speed-API.patch
+++ b/patches/api/0224-Add-Destroy-Speed-API.patch
@@ -9,7 +9,7 @@ diff --git a/src/main/java/org/bukkit/block/Block.java b/src/main/java/org/bukki
 index 85a5e9a3b41798cb3cb6687ed379a5e3eedd698a..c1705e518af08841e8154caf183bc808366feb2e 100644
 --- a/src/main/java/org/bukkit/block/Block.java
 +++ b/src/main/java/org/bukkit/block/Block.java
-@@ -681,4 +681,31 @@ public interface Block extends Metadatable, Translatable, net.kyori.adventure.tr
+@@ -690,4 +690,31 @@ public interface Block extends Metadatable, Translatable, net.kyori.adventure.tr
      @Deprecated(forRemoval = true)
      String getTranslationKey();
      // Paper end