Fix a few issues with ItemMeta (#10740)

patches/api/Expose-hasColor-to-leather-armor.patch

@@ -15,8 +15,7 @@ index 0000000000000000000000000000000000000000..00000000000000000000000000000000
 +
 +    // Paper start - Expose #hasColor to leather armor
 +    /**
-+     * Checks whether this leather armor is dyed
-+     * (i.e. has a color different from {@link ItemFactory#getDefaultLeatherColor()})
++     * Checks whether this leather armor is dyed.
 +     *
 +     * @return whether this leather armor is dyed
 +     */

patches/api/Fix-upstream-javadocs.patch

@@ -1498,6 +1498,45 @@ index 0000000000000000000000000000000000000000..00000000000000000000000000000000
       */
      void setBlockState(@NotNull BlockState blockState);
  }
+diff --git a/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java b/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java
+index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
+--- a/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java
++++ b/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java
+@@ -0,0 +0,0 @@ public interface CrossbowMeta extends ItemMeta {
+      * Removes all projectiles when given null.
+      *
+      * @param projectiles the projectiles to set
+-     * @throws IllegalArgumentException if one of the projectiles is not an
+-     * arrow or firework rocket
++     * @throws IllegalArgumentException if one of the projectiles is empty
+      */
+     void setChargedProjectiles(@Nullable List<ItemStack> projectiles);
+ 
+@@ -0,0 +0,0 @@ public interface CrossbowMeta extends ItemMeta {
+      * Adds a charged projectile to this item.
+      *
+      * @param item projectile
+-     * @throws IllegalArgumentException if the projectile is not an arrow or
+-     * firework rocket
++     * @throws IllegalArgumentException if the projectile is empty
+      */
+     void addChargedProjectile(@NotNull ItemStack item);
+ }
+diff --git a/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java b/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java
+index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
+--- a/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java
++++ b/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java
+@@ -0,0 +0,0 @@ public interface FireworkMeta extends ItemMeta {
+      * Sets the approximate power of the firework. Each level of power is half
+      * a second of flight time.
+      *
+-     * @param power the power of the firework, from 0-127
+-     * @throws IllegalArgumentException if {@literal height<0 or height>127}
++     * @param power the power of the firework, from 0-255
++     * @throws IllegalArgumentException if {@literal power < 0 or power > 255}
+      */
+     void setPower(int power) throws IllegalArgumentException;
+ 
 diff --git a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
 index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
 --- a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
@@ -1522,10 +1561,44 @@ index 0000000000000000000000000000000000000000..00000000000000000000000000000000
 - * Material#LEATHER_CHESTPLATE}, {@link Material#LEATHER_HELMET}, or {@link
 - * Material#LEATHER_LEGGINGS}) that can be colored.
 + * Material#LEATHER_LEGGINGS}, {@link Material#LEATHER_CHESTPLATE}, {@link
-+ * Material#LEATHER_HELMET}, or {@link Material#LEATHER_HORSE_ARMOR}) that can be colored.
++ * Material#LEATHER_HELMET}, {@link Material#LEATHER_HORSE_ARMOR}, {@link
++ * Material#WOLF_ARMOR}) that can be colored.
   */
  public interface LeatherArmorMeta extends ItemMeta {
  
+@@ -0,0 +0,0 @@ public interface LeatherArmorMeta extends ItemMeta {
+      * be {@link ItemFactory#getDefaultLeatherColor()}.
+      *
+      * @return the color of the armor, never null
++     * @apiNote The method yielding {@link ItemFactory#getDefaultLeatherColor()} is incorrect
++     * for {@link Material#WOLF_ARMOR} as its default color differs. Generally, it is recommended to check
++     * {@link #isDyed()} to determined if this leather armor is dyed than to compare this colour to the default.
+      */
+     @NotNull
+     Color getColor();
+@@ -0,0 +0,0 @@ public interface LeatherArmorMeta extends ItemMeta {
+     /**
+      * Sets the color of the armor.
+      *
+-     * @param color the color to set. Setting it to null is equivalent to
+-     *     setting it to {@link ItemFactory#getDefaultLeatherColor()}.
++     * @param color the color to set.
+      */
+     void setColor(@Nullable Color color);
+ 
+diff --git a/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java b/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java
+index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
+--- a/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java
++++ b/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java
+@@ -0,0 +0,0 @@ package org.bukkit.inventory.meta;
+ import org.jetbrains.annotations.NotNull;
+ 
+ /**
+- * Represents a map that can be scalable.
++ * Represents an ominous bottle with an amplifier of the bad omen effect.
+  */
+ public interface OminousBottleMeta extends ItemMeta {
+ 
 diff --git a/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java b/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java
 index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
 --- a/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java

patches/api/add-missing-Experimental-annotations.patch

@@ -973,6 +973,31 @@ index 0000000000000000000000000000000000000000..00000000000000000000000000000000
      public static final Structure TRIAL_CHAMBERS = getStructure("trial_chambers");
  
      private static Structure getStructure(String name) {
+diff --git a/src/main/java/org/bukkit/inventory/meta/BundleMeta.java b/src/main/java/org/bukkit/inventory/meta/BundleMeta.java
+index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
+--- a/src/main/java/org/bukkit/inventory/meta/BundleMeta.java
++++ b/src/main/java/org/bukkit/inventory/meta/BundleMeta.java
+@@ -0,0 +0,0 @@ import org.jetbrains.annotations.ApiStatus;
+ import org.jetbrains.annotations.NotNull;
+ import org.jetbrains.annotations.Nullable;
+ 
++@org.bukkit.MinecraftExperimental(org.bukkit.MinecraftExperimental.Requires.BUNDLE) // Paper - add missing annotation
+ @ApiStatus.Experimental
+ public interface BundleMeta extends ItemMeta {
+ 
+diff --git a/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java b/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java
+index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
+--- a/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java
++++ b/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java
+@@ -0,0 +0,0 @@ import org.jetbrains.annotations.NotNull;
+ /**
+  * Represents an ominous bottle with an amplifier of the bad omen effect.
+  */
++@org.bukkit.MinecraftExperimental(org.bukkit.MinecraftExperimental.Requires.UPDATE_1_21) // Paper - add missing annotation
++@org.jetbrains.annotations.ApiStatus.Experimental // Paper - add missing annotation
+ public interface OminousBottleMeta extends ItemMeta {
+ 
+     /**
 diff --git a/src/main/java/org/bukkit/inventory/meta/trim/TrimPattern.java b/src/main/java/org/bukkit/inventory/meta/trim/TrimPattern.java
 index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
 --- a/src/main/java/org/bukkit/inventory/meta/trim/TrimPattern.java