From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001 From: Aikar Date: Sun, 24 Mar 2019 18:39:01 -0400 Subject: [PATCH] Fix Spigot annotation mistakes while some of these may of been true, they are extreme cases and cause a ton of noise to plugin developers. These do not help plugin developers if they bring moise noise than value. diff --git a/src/main/java/org/bukkit/Bukkit.java b/src/main/java/org/bukkit/Bukkit.java index ca6f3a18ca8902b99c1c8c21b6da5def7fdb2aa8..b2acdd8bf213b779ac3afaac7026bc22eb5cdb8d 100644 --- a/src/main/java/org/bukkit/Bukkit.java +++ b/src/main/java/org/bukkit/Bukkit.java @@ -1699,7 +1699,7 @@ public final class Bukkit { * * @return the scoreboard manager or null if no worlds are loaded. */ - @Nullable + @NotNull // Paper public static ScoreboardManager getScoreboardManager() { return server.getScoreboardManager(); } @@ -1996,7 +1996,7 @@ public final class Bukkit { * @param clazz the class of the tag entries * @return the tag or null */ - @Nullable + @UndefinedNullability // Paper public static Tag getTag(@NotNull String registry, @NotNull NamespacedKey tag, @NotNull Class clazz) { return server.getTag(registry, tag, clazz); } diff --git a/src/main/java/org/bukkit/Location.java b/src/main/java/org/bukkit/Location.java index 57cb548683f7b2972c998afd34176952426f8b47..d4c87bfed81b2d73919705912f59fab05c0ee61b 100644 --- a/src/main/java/org/bukkit/Location.java +++ b/src/main/java/org/bukkit/Location.java @@ -46,7 +46,7 @@ public class Location implements Cloneable, ConfigurationSerializable { * @param y The y-coordinate of this new location * @param z The z-coordinate of this new location */ - public Location(@Nullable final World world, final double x, final double y, final double z) { + public Location(@UndefinedNullability final World world, final double x, final double y, final double z) { // Paper this(world, x, y, z, 0, 0); } @@ -60,7 +60,7 @@ public class Location implements Cloneable, ConfigurationSerializable { * @param yaw The absolute rotation on the x-plane, in degrees * @param pitch The absolute rotation on the y-plane, in degrees */ - public Location(@Nullable final World world, final double x, final double y, final double z, final float yaw, final float pitch) { + public Location(@UndefinedNullability final World world, final double x, final double y, final double z, final float yaw, final float pitch) { // Paper if (world != null) { this.world = new WeakReference<>(world); } @@ -102,7 +102,7 @@ public class Location implements Cloneable, ConfigurationSerializable { * @throws IllegalArgumentException when world is unloaded * @see #isWorldLoaded() */ - @Nullable + @UndefinedNullability // Paper public World getWorld() { if (this.world == null) { return null; diff --git a/src/main/java/org/bukkit/Material.java b/src/main/java/org/bukkit/Material.java index 53d1609e2a75c007cb7e5e8f963b0deb53bae5f7..a8561434d56f7db7e4f52283759b282e9c2116a2 100644 --- a/src/main/java/org/bukkit/Material.java +++ b/src/main/java/org/bukkit/Material.java @@ -4003,11 +4003,11 @@ public enum Material implements Keyed { } /** - * Do not use for any reason. + * Checks if this constant is a legacy material. * * @return legacy status */ - @Deprecated + // @Deprecated // Paper - this is useful, don't deprecate public boolean isLegacy() { return legacy; } diff --git a/src/main/java/org/bukkit/NamespacedKey.java b/src/main/java/org/bukkit/NamespacedKey.java index 01bcb3a1bdb5accdf844d0178cec3d25746b3eaa..236c9aea9ffc36269e5c32eacc9f1fd6bd039c88 100644 --- a/src/main/java/org/bukkit/NamespacedKey.java +++ b/src/main/java/org/bukkit/NamespacedKey.java @@ -39,12 +39,14 @@ public final class NamespacedKey implements net.kyori.adventure.key.Key, com.des /** * Create a key in a specific namespace. + *

+ * For most plugin related code, you should prefer using the + * {@link NamespacedKey#NamespacedKey(Plugin, String)} constructor. * * @param namespace namespace * @param key key - * @deprecated should never be used by plugins, for internal use only!! + * @see #NamespacedKey(Plugin, String) */ - @Deprecated public NamespacedKey(@NotNull String namespace, @NotNull String key) { Preconditions.checkArgument(namespace != null && VALID_NAMESPACE.matcher(namespace).matches(), "Invalid namespace. Must be [a-z0-9._-]: %s", namespace); Preconditions.checkArgument(key != null && VALID_KEY.matcher(key).matches(), "Invalid key. Must be [a-z0-9/._-]: %s", key); diff --git a/src/main/java/org/bukkit/Server.java b/src/main/java/org/bukkit/Server.java index 28be40d6844f801c26e8359e509afc5e3dedd71f..cd2cfaf24c794bb0c64cd613d933b6fba92ed723 100644 --- a/src/main/java/org/bukkit/Server.java +++ b/src/main/java/org/bukkit/Server.java @@ -1445,7 +1445,7 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi * * @return the scoreboard manager or null if no worlds are loaded. */ - @Nullable + @NotNull // Paper ScoreboardManager getScoreboardManager(); /** diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java index f36eb8896ee84c1d3bbce17b11ed05c5f99f2e29..b8c4d25d49ea65d36b052faba8863efa813d9bc5 100644 --- a/src/main/java/org/bukkit/World.java +++ b/src/main/java/org/bukkit/World.java @@ -427,9 +427,8 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient * @param z Z-coordinate of the chunk * @return Whether the chunk was actually refreshed * - * @deprecated This method is not guaranteed to work suitably across all client implementations. */ - @Deprecated + //@Deprecated // Paper public boolean refreshChunk(int x, int z); /** diff --git a/src/main/java/org/bukkit/entity/LingeringPotion.java b/src/main/java/org/bukkit/entity/LingeringPotion.java index f124b35ec76e6cb6a1a0dc464005087043c3efd0..94a2fef0dc9e13c754cd31d5eabc1bde2dbbe6a5 100644 --- a/src/main/java/org/bukkit/entity/LingeringPotion.java +++ b/src/main/java/org/bukkit/entity/LingeringPotion.java @@ -5,4 +5,5 @@ package org.bukkit.entity; * * @deprecated lingering status depends on only on the potion item. */ +@Deprecated // Paper public interface LingeringPotion extends ThrownPotion { } diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java index 98b856d068c765a277d1e218a04e05588e18fdcb..2c3aba0b8d89d74bfa22ae01232712c8e3516b6b 100644 --- a/src/main/java/org/bukkit/entity/Player.java +++ b/src/main/java/org/bukkit/entity/Player.java @@ -1356,9 +1356,8 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM * * @param plugin Plugin that wants to hide the entity * @param entity Entity to hide - * @deprecated draft API */ - @Deprecated + @org.jetbrains.annotations.ApiStatus.Experimental // Paper public void hideEntity(@NotNull Plugin plugin, @NotNull Entity entity); /** @@ -1368,9 +1367,8 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM * * @param plugin Plugin that wants to show the entity * @param entity Entity to show - * @deprecated draft API */ - @Deprecated + @org.jetbrains.annotations.ApiStatus.Experimental // Paper public void showEntity(@NotNull Plugin plugin, @NotNull Entity entity); /** @@ -1379,9 +1377,8 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM * @param entity Entity to check * @return True if the provided entity is not being hidden from this * player - * @deprecated draft API */ - @Deprecated + @org.jetbrains.annotations.ApiStatus.Experimental // Paper public boolean canSee(@NotNull Entity entity); /** diff --git a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java index 2ff1b1308571d8f8056d3359e8a8ba4a589c3726..8eb6f4090578d9e1b12aff813840108fdeece730 100644 --- a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java +++ b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java @@ -23,7 +23,7 @@ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellab private boolean cancelled; private final Player enchanter; - public PrepareItemEnchantEvent(@NotNull final Player enchanter, @NotNull InventoryView view, @NotNull final Block table, @NotNull final ItemStack item, @NotNull final EnchantmentOffer[] offers, final int bonus) { + public PrepareItemEnchantEvent(@NotNull final Player enchanter, @NotNull InventoryView view, @NotNull final Block table, @NotNull final ItemStack item, @org.jetbrains.annotations.Nullable final EnchantmentOffer @NotNull [] offers, final int bonus) { // Paper - offers can contain null values super(view); this.enchanter = enchanter; this.table = table; @@ -68,6 +68,7 @@ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellab * @return experience level costs offered * @deprecated Use {@link #getOffers()} instead of this method */ + @Deprecated // Paper @NotNull public int[] getExpLevelCostsOffered() { int[] levelOffers = new int[offers.length]; @@ -85,8 +86,7 @@ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellab * * @return list of available enchantment offers */ - @NotNull - public EnchantmentOffer[] getOffers() { + public @org.jetbrains.annotations.Nullable EnchantmentOffer @NotNull [] getOffers() { // Paper offers can contain null values return offers; } diff --git a/src/main/java/org/bukkit/event/player/PlayerHideEntityEvent.java b/src/main/java/org/bukkit/event/player/PlayerHideEntityEvent.java index d8a73cd22268e90eb438f522b9019f826f343275..78869fdb9cf4c541dff7d67b51866914987abf18 100644 --- a/src/main/java/org/bukkit/event/player/PlayerHideEntityEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerHideEntityEvent.java @@ -15,9 +15,8 @@ import org.jetbrains.annotations.NotNull; * This event is called regardless of if the entity was within tracking range. * * @see Player#hideEntity(org.bukkit.plugin.Plugin, org.bukkit.entity.Entity) - * @deprecated draft API */ -@Deprecated +@org.jetbrains.annotations.ApiStatus.Experimental // Paper @Warning(false) public class PlayerHideEntityEvent extends PlayerEvent { diff --git a/src/main/java/org/bukkit/event/player/PlayerShowEntityEvent.java b/src/main/java/org/bukkit/event/player/PlayerShowEntityEvent.java index 5408a8c123942a56ef11597ae6cdb77e14f741e3..29bb84145be18ef9162abdfc8820f2b3f7fd0db5 100644 --- a/src/main/java/org/bukkit/event/player/PlayerShowEntityEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerShowEntityEvent.java @@ -16,9 +16,8 @@ import org.jetbrains.annotations.NotNull; * range. * * @see Player#showEntity(org.bukkit.plugin.Plugin, org.bukkit.entity.Entity) - * @deprecated draft API */ -@Deprecated +@org.jetbrains.annotations.ApiStatus.Experimental // Paper @Warning(false) public class PlayerShowEntityEvent extends PlayerEvent { diff --git a/src/main/java/org/bukkit/inventory/CraftingInventory.java b/src/main/java/org/bukkit/inventory/CraftingInventory.java index df81bac9ecff697f98941e5c8490e10391e90090..a32977ba3ba60a1c9aee6e469d5d6cd1887c55a2 100644 --- a/src/main/java/org/bukkit/inventory/CraftingInventory.java +++ b/src/main/java/org/bukkit/inventory/CraftingInventory.java @@ -21,8 +21,7 @@ public interface CraftingInventory extends Inventory { * * @return The contents. Individual entries may be null. */ - @NotNull - ItemStack[] getMatrix(); + @Nullable ItemStack @NotNull [] getMatrix(); // Paper - make array elements nullable instead array /** * Set the item in the result slot of the crafting inventory. @@ -38,7 +37,7 @@ public interface CraftingInventory extends Inventory { * @throws IllegalArgumentException if the length of contents is greater * than the size of the crafting matrix. */ - void setMatrix(@NotNull ItemStack[] contents); + void setMatrix(@Nullable ItemStack @NotNull [] contents); // Paper - make array elements nullable instead array /** * Get the current recipe formed on the crafting inventory, if any. diff --git a/src/main/java/org/bukkit/inventory/Inventory.java b/src/main/java/org/bukkit/inventory/Inventory.java index 9c6a5bdac8c3ab682bbfae04ff24b76a62bc2883..875c401153349b0f2468525e54cf10ca86430087 100644 --- a/src/main/java/org/bukkit/inventory/Inventory.java +++ b/src/main/java/org/bukkit/inventory/Inventory.java @@ -158,8 +158,7 @@ public interface Inventory extends Iterable { * * @return An array of ItemStacks from the inventory. Individual items may be null. */ - @NotNull - public ItemStack[] getContents(); + public @Nullable ItemStack @NotNull [] getContents(); // Paper - make array elements nullable instead array /** * Completely replaces the inventory's contents. Removes all existing @@ -170,7 +169,7 @@ public interface Inventory extends Iterable { * @throws IllegalArgumentException If the array has more items than the * inventory. */ - public void setContents(@NotNull ItemStack[] items) throws IllegalArgumentException; + public void setContents(@Nullable ItemStack @NotNull [] items) throws IllegalArgumentException; // Paper - make array elements nullable instead array /** * Return the contents from the section of the inventory where items can @@ -183,8 +182,7 @@ public interface Inventory extends Iterable { * * @return inventory storage contents. Individual items may be null. */ - @NotNull - public ItemStack[] getStorageContents(); + public @Nullable ItemStack @NotNull [] getStorageContents(); // Paper - make array elements nullable instead array /** * Put the given ItemStacks into the storage slots @@ -193,7 +191,7 @@ public interface Inventory extends Iterable { * @throws IllegalArgumentException If the array has more items than the * inventory. */ - public void setStorageContents(@NotNull ItemStack[] items) throws IllegalArgumentException; + public void setStorageContents(@Nullable ItemStack @NotNull [] items) throws IllegalArgumentException; // Paper - make array elements nullable instead array /** * Checks if the inventory contains any ItemStacks with the given diff --git a/src/main/java/org/bukkit/inventory/ItemFactory.java b/src/main/java/org/bukkit/inventory/ItemFactory.java index 66ffc658dba85942f179760dc6c50258e24ab903..50fe28b48d885c782278bdb53a0bbae303f4a32d 100644 --- a/src/main/java/org/bukkit/inventory/ItemFactory.java +++ b/src/main/java/org/bukkit/inventory/ItemFactory.java @@ -26,7 +26,7 @@ public interface ItemFactory { * @return a new ItemMeta that could be applied to an item stack of the * specified material */ - @Nullable + @org.bukkit.UndefinedNullability // Paper ItemMeta getItemMeta(@NotNull final Material material); /** diff --git a/src/main/java/org/bukkit/inventory/ItemStack.java b/src/main/java/org/bukkit/inventory/ItemStack.java index 487e6a6391123a4792c3bdeba869aa2bcb5922cc..3dd8205dd070901be82c2bef390df5df58b2a9a0 100644 --- a/src/main/java/org/bukkit/inventory/ItemStack.java +++ b/src/main/java/org/bukkit/inventory/ItemStack.java @@ -8,6 +8,7 @@ import java.util.Set; // Paper import org.apache.commons.lang.Validate; import org.bukkit.Bukkit; import org.bukkit.Material; +import org.bukkit.UndefinedNullability; import org.bukkit.Utility; import org.bukkit.configuration.serialization.ConfigurationSerializable; import org.bukkit.enchantments.Enchantment; @@ -68,6 +69,7 @@ public class ItemStack implements Cloneable, ConfigurationSerializable, net.kyor * @param damage durability / damage * @deprecated see {@link #setDurability(short)} */ + @Deprecated // Paper public ItemStack(@NotNull final Material type, final int amount, final short damage) { this(type, amount, damage, null); } @@ -546,7 +548,7 @@ public class ItemStack implements Cloneable, ConfigurationSerializable, net.kyor * * @return a copy of the current ItemStack's ItemData */ - @Nullable + @UndefinedNullability // Paper public ItemMeta getItemMeta() { return this.meta == null ? Bukkit.getItemFactory().getItemMeta(this.type) : this.meta.clone(); } diff --git a/src/main/java/org/bukkit/inventory/PlayerInventory.java b/src/main/java/org/bukkit/inventory/PlayerInventory.java index 62fbd7f6d8195bebcab7f704a0a485a1bbeca26c..8b5385e39f64c4df8e235a8832d91e55642421ce 100644 --- a/src/main/java/org/bukkit/inventory/PlayerInventory.java +++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java @@ -14,8 +14,7 @@ public interface PlayerInventory extends Inventory { * * @return All the ItemStacks from the armor slots. Individual items can be null. */ - @NotNull - public ItemStack[] getArmorContents(); + public @Nullable ItemStack @NotNull [] getArmorContents(); // Paper - make array elements nullable instead array /** * Get all additional ItemStacks stored in this inventory. @@ -26,8 +25,7 @@ public interface PlayerInventory extends Inventory { * * @return All additional ItemStacks. Individual items can be null. */ - @NotNull - public ItemStack[] getExtraContents(); + public @Nullable ItemStack @NotNull [] getExtraContents(); // Paper - make array elements nullable instead array /** * Return the ItemStack from the helmet slot @@ -104,9 +102,9 @@ public interface PlayerInventory extends Inventory { * * @param slot the slot to get the ItemStack * - * @return the ItemStack in the given slot or null if there is not one + * @return the ItemStack in the given slot */ - @Nullable + @NotNull // Paper public ItemStack getItem(@NotNull EquipmentSlot slot); /** diff --git a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java index 45baebc97f0aec8abc9a894bc135e4767d7c9e35..a761b8369e1f78b28146b0a4cce121e507d4a738 100644 --- a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java +++ b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java @@ -74,8 +74,10 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste /** * Checks for existence of a localized name. * + * @deprecated Use {@link ItemMeta#displayName()} and check if it is instanceof a {@link net.kyori.adventure.text.TranslatableComponent}. * @return true if this has a localized name */ + @Deprecated // Paper - Deprecate old localized API boolean hasLocalizedName(); /** @@ -84,16 +86,20 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste * Plugins should check that hasLocalizedName() returns true * before calling this method. * + * @deprecated Use {@link ItemMeta#displayName()} and cast it to a {@link net.kyori.adventure.text.TranslatableComponent}. No longer used by the client. * @return the localized name that is set */ + @Deprecated // Paper - Deprecate old localized API @NotNull String getLocalizedName(); /** * Sets the localized name. * + * @deprecated Use {@link ItemMeta#displayName(Component)} with a {@link net.kyori.adventure.text.TranslatableComponent}. No longer used by the client. * @param name the name to set */ + @Deprecated // Paper - Deprecate old localized API void setLocalizedName(@Nullable String name); /** diff --git a/src/main/java/org/bukkit/material/Step.java b/src/main/java/org/bukkit/material/Step.java index 9f502e7ee05d0512e190a1722cc112ece068c4e2..10c0465cf58d680bfa9a0f9233f94e8b6d5a9b93 100644 --- a/src/main/java/org/bukkit/material/Step.java +++ b/src/main/java/org/bukkit/material/Step.java @@ -78,6 +78,7 @@ public class Step extends TexturedMaterial { * * @deprecated Magic value */ + @Deprecated // Paper @Override protected int getTextureIndex() { return getData() & 0x7;