Paper/patches/api/0172-Fix-Spigot-annotation-mistakes.patch

From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
From: Aikar <aikar@aikar.co>
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 3ad64a11c1e67cce5e49c34d389888060bf2a962..cb0ad65e4e30c3604d655bb75c7b26a7bf4227d7 100644
--- a/src/main/java/org/bukkit/Bukkit.java
+++ b/src/main/java/org/bukkit/Bukkit.java
@@ -837,9 +837,8 @@ public final class Bukkit {
      *
      * @param id the id of the map to get
      * @return a map view if it exists, or null otherwise
-     * @deprecated Magic value
      */
-    @Deprecated
+    //@Deprecated // Paper - Not a magic value
     @Nullable
     public static MapView getMap(int id) {
         return server.getMap(id);
@@ -1231,10 +1230,8 @@ public final class Bukkit {
      * @param name the name the player to retrieve
      * @return an offline player
      * @see #getOfflinePlayer(java.util.UUID)
-     * @deprecated Persistent storage of users should be by UUID as names are no longer
-     *             unique past a single session.
      */
-    @Deprecated
+    // @Deprecated // Paper
     @NotNull
     public static OfflinePlayer getOfflinePlayer(@NotNull String name) {
         return server.getOfflinePlayer(name);
@@ -1825,7 +1822,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();
     }
diff --git a/src/main/java/org/bukkit/GrassSpecies.java b/src/main/java/org/bukkit/GrassSpecies.java
index f9c9ae463aacd593e3aa9caf037ea1e23d56c780..f8ae143acbf586d5279b44f7311ca97f3ae4ead2 100644
--- a/src/main/java/org/bukkit/GrassSpecies.java
+++ b/src/main/java/org/bukkit/GrassSpecies.java
@@ -6,7 +6,9 @@ import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents the different types of grass.
+ * @deprecated use {@link org.bukkit.block.data.BlockData}
  */
+@Deprecated // Paper
 public enum GrassSpecies {
 
     /**
diff --git a/src/main/java/org/bukkit/Location.java b/src/main/java/org/bukkit/Location.java
index 8508aa2c6fb7c9f41f3d185f5228c86dd3b8b627..f7564581c18425c903e54f949728dd3742ca7bf2 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, io.paperm
      * @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, io.paperm
      * @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, io.paperm
      * @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 d56d899ca7737b537ea55c13a384888a873f5da3..cbec3b145a44ceee20823ae0e9c8162b15726189 100644
--- a/src/main/java/org/bukkit/Material.java
+++ b/src/main/java/org/bukkit/Material.java
@@ -4468,11 +4468,11 @@ public enum Material implements Keyed, Translatable {
     }
 
     /**
-     * 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;
     }
@@ -4543,8 +4543,10 @@ public enum Material implements Keyed, Translatable {
      * Gets the MaterialData class associated with this Material
      *
      * @return MaterialData associated with this Material
+     * @deprecated use {@link #createBlockData()}
      */
     @NotNull
+    @Deprecated // Paper
     public Class<? extends MaterialData> getData() {
         Preconditions.checkArgument(legacy, "Cannot get data class of Modern Material");
         return ctor.getDeclaringClass();
diff --git a/src/main/java/org/bukkit/NamespacedKey.java b/src/main/java/org/bukkit/NamespacedKey.java
index dbc22807a33606f8fe326cc2f5f755fee5edc7aa..1416918d1924b362a688635823484f16e6adf125 100644
--- a/src/main/java/org/bukkit/NamespacedKey.java
+++ b/src/main/java/org/bukkit/NamespacedKey.java
@@ -73,12 +73,14 @@ public final class NamespacedKey implements net.kyori.adventure.key.Key, com.des
 
     /**
      * Create a key in a specific namespace.
+     * <p>
+     * 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 && isValidNamespace(namespace), "Invalid namespace. Must be [a-z0-9._-]: %s", namespace);
         Preconditions.checkArgument(key != null && isValidKey(key), "Invalid key. Must be [a-z0-9/._-]: %s", key);
diff --git a/src/main/java/org/bukkit/NetherWartsState.java b/src/main/java/org/bukkit/NetherWartsState.java
index f43209cf7b752c26718c303ca8c3e1c7d9912ad3..f0094e6fb05e526736629ad3181c8d2c16ba6ca4 100644
--- a/src/main/java/org/bukkit/NetherWartsState.java
+++ b/src/main/java/org/bukkit/NetherWartsState.java
@@ -1,5 +1,11 @@
 package org.bukkit;
 
+// Paper start
+/**
+ * @deprecated use {@link org.bukkit.block.data.BlockData} and {@link org.bukkit.block.data.Ageable}
+ */
+@Deprecated
+// Paper end
 public enum NetherWartsState {
 
     /**
diff --git a/src/main/java/org/bukkit/Registry.java b/src/main/java/org/bukkit/Registry.java
index 44b8c9111ddc93719d9f3bb23ee1799897389f52..74c81f73649507f21351fc003d00fbeca274d92a 100644
--- a/src/main/java/org/bukkit/Registry.java
+++ b/src/main/java/org/bukkit/Registry.java
@@ -184,14 +184,14 @@ public interface Registry<T extends Keyed> extends Iterable<T> {
      *
      * @see TrimMaterial
      */
-    @ApiStatus.Experimental
+    //@ApiStatus.Experimental // Paper
     Registry<TrimMaterial> TRIM_MATERIAL = Bukkit.getRegistry(TrimMaterial.class);
     /**
      * Trim patterns.
      *
      * @see TrimPattern
      */
-    @ApiStatus.Experimental
+    //@ApiStatus.Experimental // Paper
     Registry<TrimPattern> TRIM_PATTERN = Bukkit.getRegistry(TrimPattern.class);
     /**
      * Villager profession.
@@ -273,8 +273,11 @@ public interface Registry<T extends Keyed> extends Iterable<T> {
      *
      * @param input non-null input
      * @return registered object or null if does not exist
+     * @deprecated this method's behavior is broken and not useful. If you want to get an object
+     * based on its vanilla name, or a key, wrap it in a {@link NamespacedKey} object and use {@link #get(NamespacedKey)}
      */
     @Nullable
+    @Deprecated(forRemoval = true) // Paper
     default T match(@NotNull String input) {
         Preconditions.checkArgument(input != null, "input must not be null");
 
diff --git a/src/main/java/org/bukkit/SandstoneType.java b/src/main/java/org/bukkit/SandstoneType.java
index 6277451c3c6c551078c237cd767b6d70c4f585ea..10f5cfb1885833a1d2c1027c03974da45ab28e2f 100644
--- a/src/main/java/org/bukkit/SandstoneType.java
+++ b/src/main/java/org/bukkit/SandstoneType.java
@@ -6,7 +6,9 @@ import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents the three different types of Sandstone
+ * @deprecated use {@link org.bukkit.block.data.BlockData}
  */
+@Deprecated // Paper
 public enum SandstoneType {
     CRACKED(0x0),
     GLYPHED(0x1),
diff --git a/src/main/java/org/bukkit/Server.java b/src/main/java/org/bukkit/Server.java
index 3c09a5e08c2641502b7171f27d28d92d02ed39d0..49877944a385b22e5de66b4e33056ee3f592fcd7 100644
--- a/src/main/java/org/bukkit/Server.java
+++ b/src/main/java/org/bukkit/Server.java
@@ -703,9 +703,8 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      *
      * @param id the id of the map to get
      * @return a map view if it exists, or null otherwise
-     * @deprecated Magic value
      */
-    @Deprecated
+    //@Deprecated // Paper - Not a magic value
     @Nullable
     public MapView getMap(int id);
 
@@ -1034,10 +1033,8 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      * @param name the name the player to retrieve
      * @return an offline player
      * @see #getOfflinePlayer(java.util.UUID)
-     * @deprecated Persistent storage of users should be by UUID as names are no longer
-     *             unique past a single session.
      */
-    @Deprecated
+    // @Deprecated // Paper
     @NotNull
     public OfflinePlayer getOfflinePlayer(@NotNull String name);
 
@@ -1537,7 +1534,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/UndefinedNullability.java b/src/main/java/org/bukkit/UndefinedNullability.java
index 4d4265c237179470e1fd017721a8dd595f114013..3babc9df26276300392d3f92ee6e317c33643b0b 100644
--- a/src/main/java/org/bukkit/UndefinedNullability.java
+++ b/src/main/java/org/bukkit/UndefinedNullability.java
@@ -14,6 +14,7 @@ import org.jetbrains.annotations.ApiStatus;
  * suggests a bad API design.
  */
 @Retention(RetentionPolicy.CLASS)
+@java.lang.annotation.Documented // Paper
 @ApiStatus.Internal
 @Deprecated
 public @interface UndefinedNullability {
diff --git a/src/main/java/org/bukkit/Vibration.java b/src/main/java/org/bukkit/Vibration.java
index e455eb21abf121dc6ff10ff8a13dd06f67096a8f..bbc01e7c192ae6689c301670047ff114306c57cb 100644
--- a/src/main/java/org/bukkit/Vibration.java
+++ b/src/main/java/org/bukkit/Vibration.java
@@ -13,6 +13,14 @@ public class Vibration {
     private final Destination destination;
     private final int arrivalTime;
 
+    // Paper start
+    public Vibration(@NotNull Destination destination, @NotNull int arrivalTime) {
+        this.destination = destination;
+        this.arrivalTime = arrivalTime;
+        this.origin = new Location(null, 0, 0, 0); // Dummy origin because getter expects null
+    }
+
+    @Deprecated(forRemoval = true) // Paper end
     public Vibration(@NotNull Location origin, @NotNull Destination destination, int arrivalTime) {
         this.origin = origin;
         this.destination = destination;
@@ -22,9 +30,11 @@ public class Vibration {
     /**
      * Get the origin of the vibration.
      *
+     * @deprecated unused as of 1.19
      * @return origin
      */
     @NotNull
+    @Deprecated(forRemoval = true) // Paper
     public Location getOrigin() {
         return origin;
     }
diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
index be5baaf499cc76dd737d6203570e3d431c18afcf..399fe079035e4d38030d8ad930fbc89c69f251b0 100644
--- a/src/main/java/org/bukkit/World.java
+++ b/src/main/java/org/bukkit/World.java
@@ -415,9 +415,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);
 
     /**
@@ -3707,6 +3706,10 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
     // Paper end - view distance api
 
     // Spigot start
+    /**
+     * @deprecated Unsupported api
+     */
+    @Deprecated // Paper
     public class Spigot {
 
         /**
@@ -3715,8 +3718,12 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
          * @param loc The location to strike lightning
          * @param isSilent Whether this strike makes no sound
          * @return The lightning entity.
+         * @deprecated The lightning strike sound has been moved into the client and
+         * this doesn't prevent the sound being played. Use the regular (non spigot) methods instead
+         * for a consistent behavior.
          */
         @NotNull
+        @Deprecated // Paper
         public LightningStrike strikeLightning(@NotNull Location loc, boolean isSilent) {
             throw new UnsupportedOperationException("Not supported yet.");
         }
@@ -3727,14 +3734,22 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
          * @param loc The location to strike lightning
          * @param isSilent Whether this strike makes no sound
          * @return The lightning entity.
+         * @deprecated The lightning strike sound has been moved into the client and
+         * this doesn't prevent the sound being played. Use the regular (non spigot) methods instead
+         * for a consistent behavior.
          */
         @NotNull
+        @Deprecated // Paper
         public LightningStrike strikeLightningEffect(@NotNull Location loc, boolean isSilent) {
             throw new UnsupportedOperationException("Not supported yet.");
         }
     }
 
+    /**
+     * @deprecated Unsupported api
+     */
     @NotNull
+    @Deprecated // Paper
     Spigot spigot();
     // Spigot end
 
diff --git a/src/main/java/org/bukkit/block/Block.java b/src/main/java/org/bukkit/block/Block.java
index 78f6cc1a8a8de05aec6f551f8a5f425944f0ffa3..653a83b7ceb5cec1d92aed5250ae50e714fe5f9f 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 {
      * @return a list of dropped items for this type of block
      */
     @NotNull
-    Collection<ItemStack> getDrops(@NotNull ItemStack tool, @Nullable Entity entity);
+    Collection<ItemStack> getDrops(@Nullable ItemStack tool, @Nullable Entity entity); // Paper
 
     /**
      * Returns if the given item is a preferred choice to break this Block.
diff --git a/src/main/java/org/bukkit/block/BlockState.java b/src/main/java/org/bukkit/block/BlockState.java
index 7c5438fa92053cdbd7a01483a9baa4d48df07b24..a4f0a5270693e1c4af4fad827fa0a2ce753e07b5 100644
--- a/src/main/java/org/bukkit/block/BlockState.java
+++ b/src/main/java/org/bukkit/block/BlockState.java
@@ -36,8 +36,10 @@ public interface BlockState extends Metadatable {
      * Gets the metadata for this block state.
      *
      * @return block specific metadata
+     * @deprecated use {@link #getBlockData()}
      */
     @NotNull
+    @Deprecated // Paper
     MaterialData getData();
 
     /**
@@ -141,7 +143,9 @@ public interface BlockState extends Metadatable {
      * Sets the metadata for this block state.
      *
      * @param data New block specific metadata
+     * @deprecated use {@link #setBlockData(BlockData)}
      */
+    @Deprecated // Paper
     void setData(@NotNull MaterialData data);
 
     /**
diff --git a/src/main/java/org/bukkit/block/BrushableBlock.java b/src/main/java/org/bukkit/block/BrushableBlock.java
index 4bd127b3646307398e0c937c3e36ab671235b72b..f2557a87f468ee20c2d276dbfc0e9a976656c75c 100644
--- a/src/main/java/org/bukkit/block/BrushableBlock.java
+++ b/src/main/java/org/bukkit/block/BrushableBlock.java
@@ -15,7 +15,7 @@ public interface BrushableBlock extends Lootable, TileState {
      *
      * @return the item
      */
-    @Nullable
+    @org.jetbrains.annotations.NotNull // Paper
     public ItemStack getItem();
 
     /**
diff --git a/src/main/java/org/bukkit/entity/Enderman.java b/src/main/java/org/bukkit/entity/Enderman.java
index 605af1a9fc48602643aec57dd14e8c4ab657a0bc..b3085c7ff8b3e96083d209f6612c006578773c24 100644
--- a/src/main/java/org/bukkit/entity/Enderman.java
+++ b/src/main/java/org/bukkit/entity/Enderman.java
@@ -26,15 +26,19 @@ public interface Enderman extends Monster {
      * Gets the id and data of the block that the Enderman is carrying.
      *
      * @return MaterialData containing the id and data of the block
+     * @deprecated use {@link #getCarriedBlock()}
      */
     @NotNull
+    @Deprecated // Paper
     public MaterialData getCarriedMaterial();
 
     /**
      * Sets the id and data of the block that the Enderman is carrying.
      *
      * @param material data to set the carried block to
+     * @deprecated use {@link #setCarriedBlock(BlockData)}
      */
+    @Deprecated // Paper
     public void setCarriedMaterial(@NotNull MaterialData material);
 
     /**
diff --git a/src/main/java/org/bukkit/entity/LightningStrike.java b/src/main/java/org/bukkit/entity/LightningStrike.java
index c49628f2638da68e1ec126e53c8b7c74b0d81b22..8dc433baba7060df5cfe6fc10210a5a27287987d 100644
--- a/src/main/java/org/bukkit/entity/LightningStrike.java
+++ b/src/main/java/org/bukkit/entity/LightningStrike.java
@@ -84,20 +84,31 @@ public interface LightningStrike extends Entity {
     public void setCausingPlayer(@Nullable Player player);
 
     // Spigot start
+    /**
+     * @deprecated Unsupported api
+     */
+    @Deprecated // Paper
     public class Spigot extends Entity.Spigot {
 
-        /*
+        /**
          * Returns whether the strike is silent.
          *
          * @return whether the strike is silent.
+         * @deprecated The lightning strike sound has been moved into the client and
+         * this can't predict if the sound will be played or not accurately.
          */
+        @Deprecated // Paper
         public boolean isSilent() {
             throw new UnsupportedOperationException("Not supported yet.");
         }
     }
 
+    /**
+     * @deprecated Unsupported api
+     */
     @NotNull
     @Override
+    @Deprecated // Paper
     Spigot spigot();
     // Spigot end
 }
diff --git a/src/main/java/org/bukkit/entity/LingeringPotion.java b/src/main/java/org/bukkit/entity/LingeringPotion.java
index f124b35ec76e6cb6a1a0dc464005087043c3efd0..f50aaddf8582be55fd4860ad374d8f2206991897 100644
--- a/src/main/java/org/bukkit/entity/LingeringPotion.java
+++ b/src/main/java/org/bukkit/entity/LingeringPotion.java
@@ -3,6 +3,8 @@ package org.bukkit.entity;
 /**
  * Represents a thrown lingering potion bottle
  *
- * @deprecated lingering status depends on only on the potion item.
+ * @deprecated should not be used for anything, use {@link ThrownPotion} and
+ * set the potion via the methods there.
  */
+@Deprecated(forRemoval = true) // Paper
 public interface LingeringPotion extends ThrownPotion { }
diff --git a/src/main/java/org/bukkit/entity/LivingEntity.java b/src/main/java/org/bukkit/entity/LivingEntity.java
index 79fdb183887cb8153254f6ac84a981a7ffcb561c..373b3ad6b3f94655289155914aec8294cd4f2fb2 100644
--- a/src/main/java/org/bukkit/entity/LivingEntity.java
+++ b/src/main/java/org/bukkit/entity/LivingEntity.java
@@ -664,7 +664,9 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * This may have unexpected results if the entity is not in water.
      *
      * @param swimming True if the entity is swimming.
+     * @deprecated This does nothing and is immediately reverted by the server, in the next tick <!-- Paper - future note: should wait a mojang input client/server side -->
      */
+    @Deprecated // Paper
     public void setSwimming(boolean swimming);
 
     /**
diff --git a/src/main/java/org/bukkit/entity/Minecart.java b/src/main/java/org/bukkit/entity/Minecart.java
index 95c79c5fa0c4e30201f887da6467ce5f81c8a255..7f9c4d4b430a3f0276461346ff2621bacf864075 100644
--- a/src/main/java/org/bukkit/entity/Minecart.java
+++ b/src/main/java/org/bukkit/entity/Minecart.java
@@ -101,7 +101,9 @@ public interface Minecart extends Vehicle {
      * Passing a null value will set the minecart to have no display block.
      *
      * @param material the material to set as display block.
+     * @deprecated use {@link #setDisplayBlockData(BlockData)}
      */
+    @Deprecated // Paper
     public void setDisplayBlock(@Nullable MaterialData material);
 
     /**
@@ -109,8 +111,10 @@ public interface Minecart extends Vehicle {
      * This function will return the type AIR if none is set.
      *
      * @return the block displayed by this minecart.
+     * @deprecated use {@link #getDisplayBlockData()}
      */
     @NotNull
+    @Deprecated // Paper
     public MaterialData getDisplayBlock();
 
     /**
diff --git a/src/main/java/org/bukkit/entity/Projectile.java b/src/main/java/org/bukkit/entity/Projectile.java
index 906b33b7569fff5dd78258f9765e879180a52834..06e3ad9cd8f39de0ef6ead794df1492415bc4302 100644
--- a/src/main/java/org/bukkit/entity/Projectile.java
+++ b/src/main/java/org/bukkit/entity/Projectile.java
@@ -29,7 +29,7 @@ public interface Projectile extends Entity {
      * @return true if it should bounce.
      * @deprecated does not do anything
      */
-    @Deprecated
+    @Deprecated(forRemoval = true)
     public boolean doesBounce();
 
     /**
@@ -39,6 +39,6 @@ public interface Projectile extends Entity {
      * @param doesBounce whether or not it should bounce.
      * @deprecated does not do anything
      */
-    @Deprecated
+    @Deprecated(forRemoval = true)
     public void setBounce(boolean doesBounce);
 }
diff --git a/src/main/java/org/bukkit/entity/SplashPotion.java b/src/main/java/org/bukkit/entity/SplashPotion.java
index 9cb08fe7201a9f91e88c7b1ee22c17889a7bf1c3..c0fcfccdf476106b48e626a099658c04244ebff8 100644
--- a/src/main/java/org/bukkit/entity/SplashPotion.java
+++ b/src/main/java/org/bukkit/entity/SplashPotion.java
@@ -3,7 +3,8 @@ package org.bukkit.entity;
 /**
  * Represents a thrown splash potion bottle
  *
- * @deprecated splash status depends on only on the potion item.
+ * @deprecated should not be used for anything, use {@link ThrownPotion} and
+ * set the potion via the methods there.
  */
-@Deprecated
+@Deprecated(forRemoval = true) // Paper
 public interface SplashPotion extends ThrownPotion { }
diff --git a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
index e9a6e5be5f33a342f7e5c496f0f1c64b2f302ace..f0db59a556deaefefbdaca121585c0fd199c13c2 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/entity/EntityTargetLivingEntityEvent.java b/src/main/java/org/bukkit/event/entity/EntityTargetLivingEntityEvent.java
index 090ec6f96ca9b7f760389994da988c44c32b9976..e6b4d4c1722bf4a11744a421d09646b22745b138 100644
--- a/src/main/java/org/bukkit/event/entity/EntityTargetLivingEntityEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityTargetLivingEntityEvent.java
@@ -10,7 +10,7 @@ import org.jetbrains.annotations.Nullable;
  * LivingEntity's.
  */
 public class EntityTargetLivingEntityEvent extends EntityTargetEvent {
-    public EntityTargetLivingEntityEvent(@NotNull final Entity entity, @Nullable final LivingEntity target, @Nullable final TargetReason reason) {
+    public EntityTargetLivingEntityEvent(@NotNull final Entity entity, @Nullable final LivingEntity target, @NotNull final TargetReason reason) { // Paper
         super(entity, target, reason);
     }
 
diff --git a/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java b/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java
index e1123295b9511a2c610a1baf7195638f7f3e64c4..273ae8e5da0a858d3b82d1b0f5992318ff49f145 100644
--- a/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java
@@ -24,6 +24,14 @@ public class EntityToggleSwimEvent extends EntityEvent implements Cancellable {
         return cancel;
     }
 
+    /**
+     * @deprecated This does nothing, the server and the client doesn't work
+     * correctly when the server try to bypass this. A current workaround
+     * exists. If you want to cancel the switch from the ground state to the
+     * swimming state you need to disable the sprinting flag for the player after
+     * the cancel action.
+     */
+    @Deprecated // Paper
     @Override
     public void setCancelled(boolean cancel) {
         this.cancel = cancel;
diff --git a/src/main/java/org/bukkit/event/entity/SpawnerSpawnEvent.java b/src/main/java/org/bukkit/event/entity/SpawnerSpawnEvent.java
index 9353f0d09272404f42167ab8b7ad83a03620c436..f3ec8f67328b266defb31a44a36d31401d5e9371 100644
--- a/src/main/java/org/bukkit/event/entity/SpawnerSpawnEvent.java
+++ b/src/main/java/org/bukkit/event/entity/SpawnerSpawnEvent.java
@@ -12,12 +12,19 @@ import org.jetbrains.annotations.NotNull;
 public class SpawnerSpawnEvent extends EntitySpawnEvent {
     private final CreatureSpawner spawner;
 
-    public SpawnerSpawnEvent(@NotNull final Entity spawnee, @NotNull final CreatureSpawner spawner) {
+    public SpawnerSpawnEvent(@NotNull final Entity spawnee, @org.jetbrains.annotations.Nullable final CreatureSpawner spawner) { // Paper
         super(spawnee);
         this.spawner = spawner;
     }
 
-    @NotNull
+    /**
+     * Gets the spawner tile state, or null
+     * when the entity is spawned from a minecart
+     * spawner.
+     *
+     * @return the spawner tile state
+     */
+    @org.jetbrains.annotations.Nullable // Paper
     public CreatureSpawner getSpawner() {
         return spawner;
     }
diff --git a/src/main/java/org/bukkit/event/hanging/HangingBreakByEntityEvent.java b/src/main/java/org/bukkit/event/hanging/HangingBreakByEntityEvent.java
index 68517811f63838bdad41073ee26be82f95042a8e..454885e47611edd707358ddfe0a01b7acf9ad5c8 100644
--- a/src/main/java/org/bukkit/event/hanging/HangingBreakByEntityEvent.java
+++ b/src/main/java/org/bukkit/event/hanging/HangingBreakByEntityEvent.java
@@ -11,22 +11,21 @@ import org.jetbrains.annotations.Nullable;
 public class HangingBreakByEntityEvent extends HangingBreakEvent {
     private final Entity remover;
 
-    public HangingBreakByEntityEvent(@NotNull final Hanging hanging, @Nullable final Entity remover) {
+    public HangingBreakByEntityEvent(@NotNull final Hanging hanging, @NotNull final Entity remover) { // Paper
         this(hanging, remover, HangingBreakEvent.RemoveCause.ENTITY);
     }
 
-    public HangingBreakByEntityEvent(@NotNull final Hanging hanging, @Nullable final Entity remover, @NotNull final HangingBreakEvent.RemoveCause cause) {
+    public HangingBreakByEntityEvent(@NotNull final Hanging hanging, @NotNull final Entity remover, @NotNull final HangingBreakEvent.RemoveCause cause) { // Paper
         super(hanging, cause);
         this.remover = remover;
     }
 
     /**
      * Gets the entity that removed the hanging entity.
-     * May be null, for example when broken by an explosion.
      *
      * @return the entity that removed the hanging entity
      */
-    @Nullable
+    @NotNull // Paper
     public Entity getRemover() {
         return remover;
     }
diff --git a/src/main/java/org/bukkit/event/inventory/HopperInventorySearchEvent.java b/src/main/java/org/bukkit/event/inventory/HopperInventorySearchEvent.java
index 80a0a4ad813d6453b30273d25942e6612bb05c1b..18bb808e73c7a78f367ccdb44d5fe12bc54672cb 100644
--- a/src/main/java/org/bukkit/event/inventory/HopperInventorySearchEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/HopperInventorySearchEvent.java
@@ -34,7 +34,7 @@ public class HopperInventorySearchEvent extends BlockEvent {
         DESTINATION;
     }
 
-    public HopperInventorySearchEvent(@NotNull Inventory inventory, @NotNull ContainerType containerType, @NotNull Block hopper, @NotNull Block searchBlock) {
+    public HopperInventorySearchEvent(@Nullable Inventory inventory, @NotNull ContainerType containerType, @NotNull Block hopper, @NotNull Block searchBlock) { // Paper
         super(hopper);
         this.inventory = inventory;
         this.containerType = containerType;
diff --git a/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java b/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
index fe58058f9b5d29388d48115cc81dc48ab08c58c1..ac67a4e321f43d1ede09dafe2daa1f07de8a923f 100644
--- a/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
@@ -85,7 +85,7 @@ public class InventoryClickEvent extends InventoryInteractEvent {
      *
      * @return the cursor ItemStack
      */
-    @Nullable
+    @NotNull // Paper - fix nullability
     public ItemStack getCursor() {
         return getView().getCursor();
     }
diff --git a/src/main/java/org/bukkit/event/player/PlayerBedLeaveEvent.java b/src/main/java/org/bukkit/event/player/PlayerBedLeaveEvent.java
index 1cb70b5c8776863f44f1c4cdde152c35cb51edb5..f09b378508fcc6299e7cb40f174028f6f88ba067 100644
--- a/src/main/java/org/bukkit/event/player/PlayerBedLeaveEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerBedLeaveEvent.java
@@ -43,7 +43,10 @@ public class PlayerBedLeaveEvent extends PlayerEvent implements Cancellable {
      * {@link Player#setBedSpawnLocation(Location)}.
      *
      * @return true if the spawn location will be changed
+     * @deprecated the respawn point is now set when the player enter the bed and
+     * this option doesn't work since MC 1.15.
      */
+    @Deprecated(forRemoval = true) // Paper - Unused
     public boolean shouldSetSpawnLocation() {
         return setBedSpawn;
     }
@@ -59,7 +62,10 @@ public class PlayerBedLeaveEvent extends PlayerEvent implements Cancellable {
      * {@link Player#setBedSpawnLocation(Location)}.
      *
      * @param setBedSpawn true to change the new spawn location
+     * @deprecated the respawn point is now set when the player enter the bed and
+     * this option doesn't work since MC 1.15.
      */
+    @Deprecated(forRemoval = true) // Paper - Unused
     public void setSpawnLocation(boolean setBedSpawn) {
         this.setBedSpawn = setBedSpawn;
     }
diff --git a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
index 1b2267f4e8ebded198773ec80e2bff2c861c7084..1a58734d919fae247eeb85dd785fd59990856505 100644
--- a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
@@ -78,7 +78,7 @@ public class PlayerMoveEvent extends PlayerEvent implements Cancellable {
      *
      * @return Location the player moved to
      */
-    @Nullable
+    @NotNull // Paper
     public Location getTo() {
         return to;
     }
diff --git a/src/main/java/org/bukkit/event/raid/RaidSpawnWaveEvent.java b/src/main/java/org/bukkit/event/raid/RaidSpawnWaveEvent.java
index cd58dd7de781823804701fc023706e805c0142a8..1b8bb5241efcf4a90fd098f2000f8394072dca4a 100644
--- a/src/main/java/org/bukkit/event/raid/RaidSpawnWaveEvent.java
+++ b/src/main/java/org/bukkit/event/raid/RaidSpawnWaveEvent.java
@@ -19,7 +19,7 @@ public class RaidSpawnWaveEvent extends RaidEvent {
     private final List<Raider> raiders;
     private final Raider leader;
 
-    public RaidSpawnWaveEvent(@NotNull Raid raid, @NotNull World world, @Nullable Raider leader, @NotNull List<Raider> raiders) {
+    public RaidSpawnWaveEvent(@NotNull Raid raid, @NotNull World world, @NotNull Raider leader, @NotNull List<Raider> raiders) { // Paper
         super(raid, world);
         this.raiders = raiders;
         this.leader = leader;
@@ -30,7 +30,7 @@ public class RaidSpawnWaveEvent extends RaidEvent {
      *
      * @return {@link Raider}
      */
-    @Nullable
+    @NotNull // Paper
     public Raider getPatrolLeader() {
         return leader;
     }
diff --git a/src/main/java/org/bukkit/event/vehicle/VehicleEntityCollisionEvent.java b/src/main/java/org/bukkit/event/vehicle/VehicleEntityCollisionEvent.java
index 6bafc62e2235a6b783cbf96f4dabeeaf02bd5178..50c762d777ac90a05772501a28cacff8fd3f5126 100644
--- a/src/main/java/org/bukkit/event/vehicle/VehicleEntityCollisionEvent.java
+++ b/src/main/java/org/bukkit/event/vehicle/VehicleEntityCollisionEvent.java
@@ -36,18 +36,22 @@ public class VehicleEntityCollisionEvent extends VehicleCollisionEvent implement
         this.cancelled = cancel;
     }
 
+    @Deprecated(forRemoval = true) // Paper - Unused
     public boolean isPickupCancelled() {
         return cancelledPickup;
     }
 
+    @Deprecated(forRemoval = true) // Paper - Unused
     public void setPickupCancelled(boolean cancel) {
         cancelledPickup = cancel;
     }
 
+    @Deprecated(forRemoval = true) // Paper - Unused
     public boolean isCollisionCancelled() {
         return cancelledCollision;
     }
 
+    @Deprecated(forRemoval = true) // Paper - Unused
     public void setCollisionCancelled(boolean cancel) {
         cancelledCollision = cancel;
     }
diff --git a/src/main/java/org/bukkit/generator/ChunkGenerator.java b/src/main/java/org/bukkit/generator/ChunkGenerator.java
index c0b749a5bbf4980d01fed74768bb61909b579cb9..7e7a53b41013f1bf8956c0e278820f18d77b2f0d 100644
--- a/src/main/java/org/bukkit/generator/ChunkGenerator.java
+++ b/src/main/java/org/bukkit/generator/ChunkGenerator.java
@@ -656,7 +656,9 @@ public abstract class ChunkGenerator {
          * @param y the y location in the chunk from minHeight (inclusive) - maxHeight (exclusive)
          * @param z the z location in the chunk from 0-15 inclusive
          * @param material the type to set the block to
+         * @deprecated use {@link #setBlock(int, int, int, BlockData)}
          */
+        @Deprecated // Paper
         public void setBlock(int x, int y, int z, @NotNull MaterialData material);
 
         /**
@@ -700,7 +702,9 @@ public abstract class ChunkGenerator {
          * @param yMax maximum y location (exclusive) in the chunk to set
          * @param zMax maximum z location (exclusive) in the chunk to set
          * @param material the type to set the blocks to
+         * @deprecated use {@link #setRegion(int, int, int, int, int, int, BlockData)}
          */
+        @Deprecated // Paper
         public void setRegion(int xMin, int yMin, int zMin, int xMax, int yMax, int zMax, @NotNull MaterialData material);
 
         /**
@@ -741,8 +745,10 @@ public abstract class ChunkGenerator {
          * @param y the y location in the chunk from minHeight (inclusive) - maxHeight (exclusive)
          * @param z the z location in the chunk from 0-15 inclusive
          * @return the type and data of the block or the MaterialData for air if x, y or z are outside the chunk's bounds
+         * @deprecated use {@link #getBlockData(int, int, int)}
          */
         @NotNull
+        @Deprecated // Paper
         public MaterialData getTypeAndData(int x, int y, int z);
 
         /**
diff --git a/src/main/java/org/bukkit/inventory/CookingRecipe.java b/src/main/java/org/bukkit/inventory/CookingRecipe.java
index 571652ba8843a9493f1843523e24145baa958637..f7fa79393aef40027446b78bac8e9490cfafd8bc 100644
--- a/src/main/java/org/bukkit/inventory/CookingRecipe.java
+++ b/src/main/java/org/bukkit/inventory/CookingRecipe.java
@@ -68,7 +68,9 @@ public abstract class CookingRecipe<T extends CookingRecipe> implements Recipe,
      * Get the input material.
      *
      * @return The input material.
+     * @deprecated Use {@link #getInputChoice()} instead for more complete data.
      */
+    @Deprecated // Paper
     @NotNull
     public ItemStack getInput() {
         return this.ingredient.getItemStack();
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/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java
index c69904f3ee7f3a41d6cebcd401abf8385dfbf868..62c1c3f01fd58db39f635eee415fcbc19fb36ec9 100644
--- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
+++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
@@ -511,6 +511,6 @@ public interface EntityEquipment {
      *
      * @return the entity this EntityEquipment belongs to
      */
-    @Nullable
+    @NotNull // Paper
     Entity getHolder();
 }
diff --git a/src/main/java/org/bukkit/inventory/FurnaceRecipe.java b/src/main/java/org/bukkit/inventory/FurnaceRecipe.java
index 1d442dc16cbb0fed21714d47007f3f11e30c57d4..af8f7b88edf0fa790edcf16356a030c4834f531e 100644
--- a/src/main/java/org/bukkit/inventory/FurnaceRecipe.java
+++ b/src/main/java/org/bukkit/inventory/FurnaceRecipe.java
@@ -67,8 +67,10 @@ public class FurnaceRecipe extends CookingRecipe<FurnaceRecipe> {
      *
      * @param input The input material.
      * @return The changed recipe, so you can chain calls.
+     * @deprecated use {@link #setInputChoice(RecipeChoice)}
      */
     @NotNull
+    @Deprecated
     public FurnaceRecipe setInput(@NotNull MaterialData input) {
         return setInput(input.getItemType(), input.getData());
     }
diff --git a/src/main/java/org/bukkit/inventory/Inventory.java b/src/main/java/org/bukkit/inventory/Inventory.java
index f1a48eab1a357ae64545e1f1dc941c383cff8707..466d1bd7089b76f48f953e1a51c611ecd93dcd54 100644
--- a/src/main/java/org/bukkit/inventory/Inventory.java
+++ b/src/main/java/org/bukkit/inventory/Inventory.java
@@ -161,8 +161,7 @@ public interface Inventory extends Iterable<ItemStack> {
      *
      * @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
@@ -173,7 +172,7 @@ public interface Inventory extends Iterable<ItemStack> {
      * @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
@@ -186,8 +185,7 @@ public interface Inventory extends Iterable<ItemStack> {
      *
      * @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
@@ -196,7 +194,7 @@ public interface Inventory extends Iterable<ItemStack> {
      * @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/InventoryView.java b/src/main/java/org/bukkit/inventory/InventoryView.java
index 002acfbdce1db10f7ba1b6a013e678f504ac6e69..aac9180fa3bcbdb0c17dcf96c86647b54ccc28c3 100644
--- a/src/main/java/org/bukkit/inventory/InventoryView.java
+++ b/src/main/java/org/bukkit/inventory/InventoryView.java
@@ -210,10 +210,10 @@ public abstract class InventoryView {
     /**
      * Get the item on the cursor of one of the viewing players.
      *
-     * @return The item on the player's cursor, or null if they aren't holding
-     *     one.
+     * @return The item on the player's cursor, or an empty stack
+     * if they aren't holding one.
      */
-    @Nullable
+    @NotNull // Paper - fix nullability
     public final ItemStack getCursor() {
         return getPlayer().getItemOnCursor();
     }
diff --git a/src/main/java/org/bukkit/inventory/ItemFactory.java b/src/main/java/org/bukkit/inventory/ItemFactory.java
index 74cd662d0594f2fbc5aa30ba64d9e4928145dbb9..856751439b6599943d85203a59efd691ddbd89e9 100644
--- a/src/main/java/org/bukkit/inventory/ItemFactory.java
+++ b/src/main/java/org/bukkit/inventory/ItemFactory.java
@@ -27,7 +27,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 83a0631a80db156ace1d977df71d5fc653b70bb6..60a25898fb17c467ffae05039fcd4d3b154a99ff 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.Map;
 import org.bukkit.Bukkit;
 import org.bukkit.Material;
 import org.bukkit.Translatable;
+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, Translat
      * @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);
     }
@@ -169,8 +171,10 @@ public class ItemStack implements Cloneable, ConfigurationSerializable, Translat
      * Gets the MaterialData for this stack of items
      *
      * @return MaterialData for this item
+     * @deprecated cast to {@link org.bukkit.inventory.meta.BlockDataMeta} and use {@link org.bukkit.inventory.meta.BlockDataMeta#getBlockData(Material)}
      */
     @Nullable
+    @Deprecated // Paper
     public MaterialData getData() {
         Material mat = Bukkit.getUnsafe().toLegacy(getType());
         if (data == null && mat != null && mat.getData() != null) {
@@ -184,7 +188,9 @@ public class ItemStack implements Cloneable, ConfigurationSerializable, Translat
      * Sets the MaterialData for this stack of items
      *
      * @param data New MaterialData for this item
+     * @deprecated cast to {@link org.bukkit.inventory.meta.BlockDataMeta} and use {@link org.bukkit.inventory.meta.BlockDataMeta#setBlockData(org.bukkit.block.data.BlockData)}
      */
+    @Deprecated // Paper
     public void setData(@Nullable MaterialData data) {
         if (data == null) {
             this.data = data;
@@ -546,7 +552,7 @@ public class ItemStack implements Cloneable, ConfigurationSerializable, Translat
      *
      * @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 5461f7fa75f5a065bb333b4a113640b5fe1e3825..c4d657727e508cb941320730a9d3aa5486712ef3 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/ShapedRecipe.java b/src/main/java/org/bukkit/inventory/ShapedRecipe.java
index 97d5d9c6347bc401e3f4ab7c0ba1391ad5b0449a..da878c6d4928ddbc16b50ace86d992685a2b7873 100644
--- a/src/main/java/org/bukkit/inventory/ShapedRecipe.java
+++ b/src/main/java/org/bukkit/inventory/ShapedRecipe.java
@@ -100,8 +100,10 @@ public class ShapedRecipe extends CraftingRecipe {
      * @param ingredient The ingredient.
      * @return The changed recipe, so you can chain calls.
      * @throws IllegalArgumentException if the {@code key} does not appear in the shape.
+     * @deprecated use {@link #setIngredient(char, RecipeChoice)}
      */
     @NotNull
+    @Deprecated // Paper
     public ShapedRecipe setIngredient(char key, @NotNull MaterialData ingredient) {
         return setIngredient(key, ingredient.getItemType(), ingredient.getData());
     }
@@ -179,7 +181,9 @@ public class ShapedRecipe extends CraftingRecipe {
      * Get a copy of the ingredients map.
      *
      * @return The mapping of character to ingredients.
+     * @deprecated Use {@link #getChoiceMap()} instead for more complete data.
      */
+    @Deprecated // Paper
     @NotNull
     public Map<Character, ItemStack> getIngredientMap() {
         HashMap<Character, ItemStack> result = new HashMap<Character, ItemStack>();
diff --git a/src/main/java/org/bukkit/inventory/ShapelessRecipe.java b/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
index b8ac602cd2718d615ec243ce648951a1a46c26ec..beb798482479c58a8628c314b510ab6349576ce8 100644
--- a/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
+++ b/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
@@ -43,8 +43,10 @@ public class ShapelessRecipe extends CraftingRecipe {
      *
      * @param ingredient The ingredient to add.
      * @return The changed recipe, so you can chain calls.
+     * @deprecated use {@link #addIngredient(RecipeChoice)}
      */
     @NotNull
+    @Deprecated
     public ShapelessRecipe addIngredient(@NotNull MaterialData ingredient) {
         return addIngredient(1, ingredient);
     }
@@ -80,8 +82,10 @@ public class ShapelessRecipe extends CraftingRecipe {
      * @param count How many to add (can't be more than 9!)
      * @param ingredient The ingredient to add.
      * @return The changed recipe, so you can chain calls.
+     * @deprecated use {@link #addIngredient(int, Material)}
      */
     @NotNull
+    @Deprecated // Paper
     public ShapelessRecipe addIngredient(int count, @NotNull MaterialData ingredient) {
         return addIngredient(count, ingredient.getItemType(), ingredient.getData());
     }
@@ -198,8 +202,10 @@ public class ShapelessRecipe extends CraftingRecipe {
      *
      * @param ingredient The ingredient to remove
      * @return The changed recipe.
+     * @deprecated use {@link #removeIngredient(Material)}
      */
     @NotNull
+    @Deprecated // Paper
     public ShapelessRecipe removeIngredient(@NotNull MaterialData ingredient) {
         return removeIngredient(ingredient.getItemType(), ingredient.getData());
     }
@@ -226,8 +232,10 @@ public class ShapelessRecipe extends CraftingRecipe {
      * @param count The number of copies to remove.
      * @param ingredient The ingredient to remove.
      * @return The changed recipe.
+     * @deprecated use {@link #removeIngredient(int, Material)}
      */
     @NotNull
+    @Deprecated // Paper
     public ShapelessRecipe removeIngredient(int count, @NotNull MaterialData ingredient) {
         return removeIngredient(count, ingredient.getItemType(), ingredient.getData());
     }
@@ -277,7 +285,9 @@ public class ShapelessRecipe extends CraftingRecipe {
      * Get the list of ingredients used for this recipe.
      *
      * @return The input list
+     * @deprecated Use {@link #getChoiceList()} instead for more complete data.
      */
+    @Deprecated // Paper
     @NotNull
     public List<ItemStack> getIngredientList() {
         ArrayList<ItemStack> result = new ArrayList<ItemStack>(ingredients.size());
diff --git a/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java b/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
index 597a18a767b68b47e81454b7d44613c7178c1366..bc3440eb72127824b3961fbdae583bb61385f65e 100644
--- a/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
+++ b/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
@@ -57,7 +57,9 @@ public class StonecuttingRecipe implements Recipe, Keyed {
      * Get the input material.
      *
      * @return The input material.
+     * @deprecated Use {@link #getInputChoice()} instead for more complete data.
      */
+    @Deprecated // Paper
     @NotNull
     public ItemStack getInput() {
         return this.ingredient.getItemStack();
diff --git a/src/main/java/org/bukkit/inventory/meta/ColorableArmorMeta.java b/src/main/java/org/bukkit/inventory/meta/ColorableArmorMeta.java
index 5ccae862dbac393805a47fe26c18a2f33f1e140d..72281899817c5c140cdca2afff75fbcebd942532 100644
--- a/src/main/java/org/bukkit/inventory/meta/ColorableArmorMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/ColorableArmorMeta.java
@@ -6,7 +6,7 @@ import org.jetbrains.annotations.NotNull;
 /**
  * Represents armor that an entity can equip and can also be colored.
  */
-@ApiStatus.Experimental
+//@ApiStatus.Experimental // Paper
 public interface ColorableArmorMeta extends ArmorMeta, LeatherArmorMeta {
 
     @Override
diff --git a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
index 55e9dc5d1d87fbc9d0dabbb7bd59584fe2c5f379..5c1ca0e47f0ac1525c3d37b55f52874878f44c28 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 <code>true</code>
      * 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/inventory/meta/MapMeta.java b/src/main/java/org/bukkit/inventory/meta/MapMeta.java
index 32055a8890425e0b819930f3059da5ea9dfca553..26a336dade83baee97d20eb39a058925659f5777 100644
--- a/src/main/java/org/bukkit/inventory/meta/MapMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/MapMeta.java
@@ -16,13 +16,8 @@ public interface MapMeta extends ItemMeta {
      *
      * @return true if this has a map ID number.
      * @see #hasMapView()
-     * @deprecated These methods are poor API: They rely on the caller to pass
-     * in an only an integer property, and have poorly defined implementation
-     * behavior if that integer is not a valid map (the current implementation
-     * for example will generate a new map with a different ID). The xxxMapView
-     * family of methods should be used instead.
      */
-    @Deprecated
+    //@Deprecated // Paper
     boolean hasMapId();
 
     /**
@@ -34,13 +29,8 @@ public interface MapMeta extends ItemMeta {
      *
      * @return the map ID that is set
      * @see #getMapView()
-     * @deprecated These methods are poor API: They rely on the caller to pass
-     * in an only an integer property, and have poorly defined implementation
-     * behavior if that integer is not a valid map (the current implementation
-     * for example will generate a new map with a different ID). The xxxMapView
-     * family of methods should be used instead.
      */
-    @Deprecated
+    //@Deprecated // Paper
     int getMapId();
 
     /**
diff --git a/src/main/java/org/bukkit/material/Openable.java b/src/main/java/org/bukkit/material/Openable.java
index 0ae54f973d11df74abb3105cf9226afb130b4f33..597036bad6bc61b4aa63a61b45e886dd74a0b7f6 100644
--- a/src/main/java/org/bukkit/material/Openable.java
+++ b/src/main/java/org/bukkit/material/Openable.java
@@ -1,5 +1,6 @@
 package org.bukkit.material;
 
+@Deprecated // Paper
 public interface Openable {
 
     /**
diff --git a/src/main/java/org/bukkit/material/Redstone.java b/src/main/java/org/bukkit/material/Redstone.java
index 3e46603f8cd38041394e0e1baf788d9009b3ffc7..b15c141f1db07296bb349f11c6f39b0fbe53e7b1 100644
--- a/src/main/java/org/bukkit/material/Redstone.java
+++ b/src/main/java/org/bukkit/material/Redstone.java
@@ -3,6 +3,7 @@ package org.bukkit.material;
 /**
  * Indicated a Material that may carry or create a Redstone current
  */
+@Deprecated // Paper
 public interface Redstone {
 
     /**
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;
diff --git a/src/main/java/org/bukkit/material/types/MushroomBlockTexture.java b/src/main/java/org/bukkit/material/types/MushroomBlockTexture.java
index 0ea9c6b2420a0f990bd1fdf50fc015e37a7060d8..e99644eae1c662b117aa19060d2484aca19fe0a4 100644
--- a/src/main/java/org/bukkit/material/types/MushroomBlockTexture.java
+++ b/src/main/java/org/bukkit/material/types/MushroomBlockTexture.java
@@ -7,7 +7,9 @@ import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents the different textured blocks of mushroom.
+ * @deprecated use BlockData
  */
+@Deprecated // Paper
 public enum MushroomBlockTexture {
 
     /**
diff --git a/src/test/java/org/bukkit/materials/MaterialDataTest.java b/src/test/java/org/bukkit/materials/MaterialDataTest.java
index 8d78435cc42a9e668b2d4d674b79b4094c3bd1b1..24a8ce4387b897c717b55405f363ffafff45894d 100644
--- a/src/test/java/org/bukkit/materials/MaterialDataTest.java
+++ b/src/test/java/org/bukkit/materials/MaterialDataTest.java
@@ -22,6 +22,7 @@ import org.bukkit.material.WoodenStep;
 import org.bukkit.material.types.MushroomBlockTexture;
 import org.junit.jupiter.api.Test;
 
+@Deprecated // Paper
 public class MaterialDataTest {
 
     @Test