PaperMC/patches/api/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.

Use ApiStatus.Internal instead of Deprecated for actual internal API
that continues to have use (internally).

These do not help plugin developers if they bring moise noise than value.

diff --git a/src/main/java/org/bukkit/Art.java b/src/main/java/org/bukkit/Art.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/Art.java
+++ b/src/main/java/org/bukkit/Art.java
@@ -0,0 +0,0 @@ public enum Art implements Keyed {
      * Get the ID of this painting.
      *
      * @return The ID of this painting
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     public int getId() {
         return id;
     }
@@ -0,0 +0,0 @@ public enum Art implements Keyed {
      *
      * @param id The ID
      * @return The painting
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     @Nullable
     public static Art getById(int id) {
         return BY_ID.get(id);
diff --git a/src/main/java/org/bukkit/Bukkit.java b/src/main/java/org/bukkit/Bukkit.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/Bukkit.java
+++ b/src/main/java/org/bukkit/Bukkit.java
@@ -0,0 +0,0 @@ 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);
@@ -0,0 +0,0 @@ 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);
@@ -0,0 +0,0 @@ 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/CoalType.java b/src/main/java/org/bukkit/CoalType.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/CoalType.java
+++ b/src/main/java/org/bukkit/CoalType.java
@@ -0,0 +0,0 @@ import org.jetbrains.annotations.Nullable;
 /**
  * Represents the two types of coal
  */
+@Deprecated // Paper
 public enum CoalType {
     COAL(0x0),
     CHARCOAL(0x1);
diff --git a/src/main/java/org/bukkit/CropState.java b/src/main/java/org/bukkit/CropState.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/CropState.java
+++ b/src/main/java/org/bukkit/CropState.java
@@ -0,0 +0,0 @@ import org.jetbrains.annotations.Nullable;
 /**
  * Represents the different growth states of crops
  */
+@Deprecated // Paper
 public enum CropState {
 
     /**
diff --git a/src/main/java/org/bukkit/Difficulty.java b/src/main/java/org/bukkit/Difficulty.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/Difficulty.java
+++ b/src/main/java/org/bukkit/Difficulty.java
@@ -0,0 +0,0 @@ public enum Difficulty {
      * Gets the difficulty value associated with this Difficulty.
      *
      * @return An integer value of this difficulty
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     public int getValue() {
         return value;
     }
@@ -0,0 +0,0 @@ public enum Difficulty {
      * @param value Value to check
      * @return Associative {@link Difficulty} with the given value, or null if
      *     it doesn't exist
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     @Nullable
     public static Difficulty getByValue(final int value) {
         return BY_ID.get(value);
diff --git a/src/main/java/org/bukkit/DyeColor.java b/src/main/java/org/bukkit/DyeColor.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/DyeColor.java
+++ b/src/main/java/org/bukkit/DyeColor.java
@@ -0,0 +0,0 @@ public enum DyeColor {
      *
      * @return A byte containing the wool data value of this color
      * @see #getDyeData()
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     public byte getWoolData() {
         return woolData;
     }
@@ -0,0 +0,0 @@ public enum DyeColor {
      * @return The {@link DyeColor} representing the given value, or null if
      *     it doesn't exist
      * @see #getByDyeData(byte)
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     @Nullable
     public static DyeColor getByWoolData(final byte data) {
         int i = 0xff & data;
@@ -0,0 +0,0 @@ public enum DyeColor {
      *
      * @param name dye name
      * @return dye color
-     * @deprecated legacy use only
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     @NotNull
     public static DyeColor legacyValueOf(@Nullable String name) {
         return "SILVER".equals(name) ? DyeColor.LIGHT_GRAY : DyeColor.valueOf(name);
diff --git a/src/main/java/org/bukkit/Effect.java b/src/main/java/org/bukkit/Effect.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/Effect.java
+++ b/src/main/java/org/bukkit/Effect.java
@@ -0,0 +0,0 @@ public enum Effect {
      * Gets the ID for this effect.
      *
      * @return ID of this effect
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     public int getId() {
         return this.id;
     }
@@ -0,0 +0,0 @@ public enum Effect {
      *
      * @param id ID of the Effect to return
      * @return Effect with the given ID
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     @Nullable
     public static Effect getById(int id) {
         return BY_ID.get(id);
diff --git a/src/main/java/org/bukkit/EntityEffect.java b/src/main/java/org/bukkit/EntityEffect.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/EntityEffect.java
+++ b/src/main/java/org/bukkit/EntityEffect.java
@@ -0,0 +0,0 @@ public enum EntityEffect {
      * Gets the data value of this EntityEffect, may not be unique.
      *
      * @return The data value
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     public byte getData() {
         return data;
     }
diff --git a/src/main/java/org/bukkit/GameMode.java b/src/main/java/org/bukkit/GameMode.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/GameMode.java
+++ b/src/main/java/org/bukkit/GameMode.java
@@ -0,0 +0,0 @@ public enum GameMode {
      * Gets the mode value associated with this GameMode
      *
      * @return An integer value of this gamemode
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     public int getValue() {
         return value;
     }
@@ -0,0 +0,0 @@ public enum GameMode {
      * @param value Value to check
      * @return Associative {@link GameMode} with the given value, or null if
      *     it doesn't exist
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     @Nullable
     public static GameMode getByValue(final int value) {
         return BY_ID.get(value);
diff --git a/src/main/java/org/bukkit/GrassSpecies.java b/src/main/java/org/bukkit/GrassSpecies.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/GrassSpecies.java
+++ b/src/main/java/org/bukkit/GrassSpecies.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/Location.java
+++ b/src/main/java/org/bukkit/Location.java
@@ -0,0 +0,0 @@ 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);
     }
 
@@ -0,0 +0,0 @@ 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);
         }
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/Material.java
+++ b/src/main/java/org/bukkit/Material.java
@@ -0,0 +0,0 @@ public enum Material implements Keyed, Translatable {
      * Do not use for any reason.
      *
      * @return ID of this material
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     public int getId() {
         Preconditions.checkArgument(legacy, "Cannot get ID of Modern Material");
         return id;
     }
 
     /**
-     * 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;
     }
@@ -0,0 +0,0 @@ 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();
@@ -0,0 +0,0 @@ public enum Material implements Keyed, Translatable {
      * material.
      *
      * @return true if this material can be interacted with.
+     * @deprecated This method is not comprehensive and does not accurately reflect what block types are
+     * interactable. Many "interactions" are defined on the item not block, and many are conditional on some other world state
+     * checks being true.
      */
+    @Deprecated // Paper
     public boolean isInteractable() {
         switch (this) {
             // <editor-fold defaultstate="collapsed" desc="isInteractable">
diff --git a/src/main/java/org/bukkit/NamespacedKey.java b/src/main/java/org/bukkit/NamespacedKey.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/NamespacedKey.java
+++ b/src/main/java/org/bukkit/NamespacedKey.java
@@ -0,0 +0,0 @@ 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
-     * @apiNote should never be used by plugins, for internal use only!!
+     * @see #NamespacedKey(Plugin, String)
      */
-    @ApiStatus.Internal
     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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/NetherWartsState.java
+++ b/src/main/java/org/bukkit/NetherWartsState.java
@@ -0,0 +0,0 @@
 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/Note.java b/src/main/java/org/bukkit/Note.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/Note.java
+++ b/src/main/java/org/bukkit/Note.java
@@ -0,0 +0,0 @@ public class Note {
          * Returns the not sharped id of this tone.
          *
          * @return the not sharped id of this tone.
-         * @deprecated Magic value
+         * @apiNote Internal Use Only
          */
-        @Deprecated
+        @org.jetbrains.annotations.ApiStatus.Internal // Paper
         public byte getId() {
             return getId(false);
         }
@@ -0,0 +0,0 @@ public class Note {
          *
          * @param sharped Set to true to return the sharped id.
          * @return the id of this tone.
-         * @deprecated Magic value
+         * @apiNote Internal Use Only
          */
-        @Deprecated
+        @org.jetbrains.annotations.ApiStatus.Internal // Paper
         public byte getId(boolean sharped) {
             byte id = (byte) (sharped && sharpable ? this.id + 1 : this.id);
 
@@ -0,0 +0,0 @@ public class Note {
          * @return if the tone id is the sharped id of the tone.
          * @throws IllegalArgumentException if neither the tone nor the
          *     semitone have the id.
-         * @deprecated Magic value
+         * @apiNote Internal Use Only
          */
-        @Deprecated
+        @org.jetbrains.annotations.ApiStatus.Internal // Paper
         public boolean isSharped(byte id) {
             if (id == getId(false)) {
                 return false;
@@ -0,0 +0,0 @@ public class Note {
          *
          * @param id the id of the tone.
          * @return the tone to id.
-         * @deprecated Magic value
+         * @apiNote Internal Use Only
          */
-        @Deprecated
+        @org.jetbrains.annotations.ApiStatus.Internal // Paper
         @Nullable
         public static Tone getById(byte id) {
             return BY_DATA.get(id);
@@ -0,0 +0,0 @@ public class Note {
      * Returns the internal id of this note.
      *
      * @return the internal id of this note.
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     public byte getId() {
         return note;
     }
diff --git a/src/main/java/org/bukkit/Particle.java b/src/main/java/org/bukkit/Particle.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/Particle.java
+++ b/src/main/java/org/bukkit/Particle.java
@@ -0,0 +0,0 @@ public enum Particle implements Keyed {
     BLOCK_CRACK("block", BlockData.class),
     /**
      * Uses {@link BlockData} as DataType
+     * @deprecated use {@link #BLOCK_CRACK}
      */
+    @Deprecated // Paper
     BLOCK_DUST("block", BlockData.class, false),
     WATER_DROP("rain"),
     MOB_APPEARANCE("elder_guardian"),
@@ -0,0 +0,0 @@ public enum Particle implements Keyed {
     // ----- Legacy Separator -----
     /**
      * Uses {@link MaterialData} as DataType
+     * @deprecated {@link MaterialData} is deprecated API
      */
+    @Deprecated // Paper
     LEGACY_BLOCK_CRACK(null, MaterialData.class, false),
     /**
      * Uses {@link MaterialData} as DataType
+     * @deprecated {@link MaterialData} is deprecated API
      */
+    @Deprecated // Paper
     LEGACY_BLOCK_DUST(null, MaterialData.class, false),
     /**
      * Uses {@link MaterialData} as DataType
+     * @deprecated {@link MaterialData} is deprecated API
      */
+    @Deprecated // Paper
     LEGACY_FALLING_DUST(null, MaterialData.class, false);
 
     private final NamespacedKey key;
diff --git a/src/main/java/org/bukkit/Registry.java b/src/main/java/org/bukkit/Registry.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/Registry.java
+++ b/src/main/java/org/bukkit/Registry.java
@@ -0,0 +0,0 @@ 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.
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/SandstoneType.java
+++ b/src/main/java/org/bukkit/SandstoneType.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/Server.java
+++ b/src/main/java/org/bukkit/Server.java
@@ -0,0 +0,0 @@ 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);
 
@@ -0,0 +0,0 @@ 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);
 
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/UndefinedNullability.java
+++ b/src/main/java/org/bukkit/UndefinedNullability.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/Vibration.java
+++ b/src/main/java/org/bukkit/Vibration.java
@@ -0,0 +0,0 @@ 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;
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/World.java
+++ b/src/main/java/org/bukkit/World.java
@@ -0,0 +0,0 @@ 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);
 
     /**
@@ -0,0 +0,0 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
     // Paper end - view distance api
 
     // Spigot start
+    /**
+     * @deprecated Unsupported api
+     */
+    @Deprecated // Paper
     public class Spigot {
 
         /**
@@ -0,0 +0,0 @@ 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.");
         }
@@ -0,0 +0,0 @@ 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
 
@@ -0,0 +0,0 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
          * Gets the dimension ID of this environment
          *
          * @return dimension ID
-         * @deprecated Magic value
+         * @apiNote Internal Use Only
          */
-        @Deprecated
+        @org.jetbrains.annotations.ApiStatus.Internal // Paper
         public int getId() {
             return id;
         }
@@ -0,0 +0,0 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
          *
          * @param id The ID of the environment
          * @return The environment
-         * @deprecated Magic value
+         * @apiNote Internal Use Only
          */
-        @Deprecated
+        @org.jetbrains.annotations.ApiStatus.Internal // Paper
         @Nullable
         public static Environment getEnvironment(int id) {
             return lookup.get(id);
diff --git a/src/main/java/org/bukkit/block/Block.java b/src/main/java/org/bukkit/block/Block.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/block/Block.java
+++ b/src/main/java/org/bukkit/block/Block.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/block/BlockState.java
+++ b/src/main/java/org/bukkit/block/BlockState.java
@@ -0,0 +0,0 @@ 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();
 
     /**
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/block/BrushableBlock.java
+++ b/src/main/java/org/bukkit/block/BrushableBlock.java
@@ -0,0 +0,0 @@ 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/block/PistonMoveReaction.java b/src/main/java/org/bukkit/block/PistonMoveReaction.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/block/PistonMoveReaction.java
+++ b/src/main/java/org/bukkit/block/PistonMoveReaction.java
@@ -0,0 +0,0 @@ public enum PistonMoveReaction {
 
     /**
      * @return The ID of the move reaction
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     public int getId() {
         return this.id;
     }
@@ -0,0 +0,0 @@ public enum PistonMoveReaction {
     /**
      * @param id An ID
      * @return The move reaction with that ID
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     @Nullable
     public static PistonMoveReaction getById(int id) {
         return byId.get(id);
diff --git a/src/main/java/org/bukkit/entity/Enderman.java b/src/main/java/org/bukkit/entity/Enderman.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/Enderman.java
+++ b/src/main/java/org/bukkit/entity/Enderman.java
@@ -0,0 +0,0 @@ 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/EntityType.java b/src/main/java/org/bukkit/entity/EntityType.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/EntityType.java
+++ b/src/main/java/org/bukkit/entity/EntityType.java
@@ -0,0 +0,0 @@ public enum EntityType implements Keyed, Translatable {
      *
      * @param name the entity type's name
      * @return the matching entity type or null
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     @Contract("null -> null")
     @Nullable
     public static EntityType fromName(@Nullable String name) {
diff --git a/src/main/java/org/bukkit/entity/LightningStrike.java b/src/main/java/org/bukkit/entity/LightningStrike.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/LightningStrike.java
+++ b/src/main/java/org/bukkit/entity/LightningStrike.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/LingeringPotion.java
+++ b/src/main/java/org/bukkit/entity/LingeringPotion.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/LivingEntity.java
+++ b/src/main/java/org/bukkit/entity/LivingEntity.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/Minecart.java
+++ b/src/main/java/org/bukkit/entity/Minecart.java
@@ -0,0 +0,0 @@ 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);
 
     /**
@@ -0,0 +0,0 @@ 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/Player.java b/src/main/java/org/bukkit/entity/Player.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/Player.java
+++ b/src/main/java/org/bukkit/entity/Player.java
@@ -0,0 +0,0 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
 
     /**
      * Forces an update of the player's entire inventory.
-     *
-     * @apiNote It should not be necessary for plugins to use this method. If it
-     * is required for some reason, it is probably a bug.
      */
-    @ApiStatus.Internal
+    // @ApiStatus.Internal // Paper - is valid API
     public void updateInventory();
 
     /**
diff --git a/src/main/java/org/bukkit/entity/Projectile.java b/src/main/java/org/bukkit/entity/Projectile.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/Projectile.java
+++ b/src/main/java/org/bukkit/entity/Projectile.java
@@ -0,0 +0,0 @@ public interface Projectile extends Entity {
      * @return true if it should bounce.
      * @deprecated does not do anything
      */
-    @Deprecated
+    @Deprecated(forRemoval = true)
     public boolean doesBounce();
 
     /**
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/SplashPotion.java
+++ b/src/main/java/org/bukkit/entity/SplashPotion.java
@@ -0,0 +0,0 @@ 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/entity/TextDisplay.java b/src/main/java/org/bukkit/entity/TextDisplay.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/TextDisplay.java
+++ b/src/main/java/org/bukkit/entity/TextDisplay.java
@@ -0,0 +0,0 @@ public interface TextDisplay extends Display {
      * Gets the text background color.
      *
      * @return the background color
-     * @deprecated API subject to change
      */
     @Nullable
-    @Deprecated
+    // @Deprecated // Paper - is stable API
     Color getBackgroundColor();
 
     /**
      * Sets the text background color.
      *
      * @param color new background color
-     * @deprecated API subject to change
      */
-    @Deprecated
+    // @Deprecated // Paper - is stable API
     void setBackgroundColor(@Nullable Color color);
 
     /**
diff --git a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
+++ b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
@@ -0,0 +0,0 @@ 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;
@@ -0,0 +0,0 @@ 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];
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/entity/EntityTargetLivingEntityEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityTargetLivingEntityEvent.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java
@@ -0,0 +0,0 @@ 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/ProjectileHitEvent.java b/src/main/java/org/bukkit/event/entity/ProjectileHitEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/entity/ProjectileHitEvent.java
+++ b/src/main/java/org/bukkit/event/entity/ProjectileHitEvent.java
@@ -0,0 +0,0 @@ public class ProjectileHitEvent extends EntityEvent implements Cancellable {
     private final BlockFace hitFace;
     private boolean cancel = false;
 
+    @Deprecated @io.papermc.paper.annotation.DoNotUse // Paper
     public ProjectileHitEvent(@NotNull final Projectile projectile) {
-        this(projectile, null, null);
+        this(projectile, null, null, null); // Paper
     }
 
+    @Deprecated @io.papermc.paper.annotation.DoNotUse // Paper
     public ProjectileHitEvent(@NotNull final Projectile projectile, @Nullable Entity hitEntity) {
-        this(projectile, hitEntity, null);
+        this(projectile, hitEntity, null, null); // Paper
     }
 
+    @Deprecated @io.papermc.paper.annotation.DoNotUse // Paper
     public ProjectileHitEvent(@NotNull final Projectile projectile, @Nullable Block hitBlock) {
-        this(projectile, null, hitBlock);
+        this(projectile, null, hitBlock, null); // Paper
     }
 
+    @Deprecated @io.papermc.paper.annotation.DoNotUse // Paper
     public ProjectileHitEvent(@NotNull final Projectile projectile, @Nullable Entity hitEntity, @Nullable Block hitBlock) {
         this(projectile, hitEntity, hitBlock, null);
     }
 
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     public ProjectileHitEvent(@NotNull final Projectile projectile, @Nullable Entity hitEntity, @Nullable Block hitBlock, @Nullable BlockFace hitFace) {
         super(projectile);
         this.hitEntity = hitEntity;
diff --git a/src/main/java/org/bukkit/event/entity/SpawnerSpawnEvent.java b/src/main/java/org/bukkit/event/entity/SpawnerSpawnEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/entity/SpawnerSpawnEvent.java
+++ b/src/main/java/org/bukkit/event/entity/SpawnerSpawnEvent.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/hanging/HangingBreakByEntityEvent.java
+++ b/src/main/java/org/bukkit/event/hanging/HangingBreakByEntityEvent.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/inventory/HopperInventorySearchEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/HopperInventorySearchEvent.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/player/PlayerBedLeaveEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerBedLeaveEvent.java
@@ -0,0 +0,0 @@ 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;
     }
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/raid/RaidSpawnWaveEvent.java
+++ b/src/main/java/org/bukkit/event/raid/RaidSpawnWaveEvent.java
@@ -0,0 +0,0 @@ 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;
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/vehicle/VehicleEntityCollisionEvent.java
+++ b/src/main/java/org/bukkit/event/vehicle/VehicleEntityCollisionEvent.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/generator/ChunkGenerator.java
+++ b/src/main/java/org/bukkit/generator/ChunkGenerator.java
@@ -0,0 +0,0 @@ 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);
 
         /**
@@ -0,0 +0,0 @@ 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);
 
         /**
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/CookingRecipe.java
+++ b/src/main/java/org/bukkit/inventory/CookingRecipe.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/CraftingInventory.java
+++ b/src/main/java/org/bukkit/inventory/CraftingInventory.java
@@ -0,0 +0,0 @@ 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.
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
+++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/FurnaceRecipe.java
+++ b/src/main/java/org/bukkit/inventory/FurnaceRecipe.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/Inventory.java
+++ b/src/main/java/org/bukkit/inventory/Inventory.java
@@ -0,0 +0,0 @@ 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
@@ -0,0 +0,0 @@ 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
@@ -0,0 +0,0 @@ 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
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/InventoryView.java
+++ b/src/main/java/org/bukkit/inventory/InventoryView.java
@@ -0,0 +0,0 @@ public abstract class InventoryView {
          * Gets the id of this view.
          *
          * @return the id of this view
-         * @deprecated Magic value
+         * @apiNote Internal Use Only
          */
-        @Deprecated
+        @org.jetbrains.annotations.ApiStatus.Internal // Paper
         public int getId() {
             return id;
         }
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/ItemFactory.java
+++ b/src/main/java/org/bukkit/inventory/ItemFactory.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/ItemStack.java
+++ b/src/main/java/org/bukkit/inventory/ItemStack.java
@@ -0,0 +0,0 @@ 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;
@@ -0,0 +0,0 @@ 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);
     }
@@ -0,0 +0,0 @@ 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) {
@@ -0,0 +0,0 @@ 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;
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/PlayerInventory.java
+++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java
@@ -0,0 +0,0 @@ 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.
@@ -0,0 +0,0 @@ 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
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/ShapedRecipe.java
+++ b/src/main/java/org/bukkit/inventory/ShapedRecipe.java
@@ -0,0 +0,0 @@ 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());
     }
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
+++ b/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
@@ -0,0 +0,0 @@ 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);
     }
@@ -0,0 +0,0 @@ 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());
     }
@@ -0,0 +0,0 @@ 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());
     }
@@ -0,0 +0,0 @@ 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());
     }
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
+++ b/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/meta/ColorableArmorMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/ColorableArmorMeta.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
@@ -0,0 +0,0 @@ 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();
 
     /**
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/meta/MapMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/MapMeta.java
@@ -0,0 +0,0 @@ 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();
 
     /**
@@ -0,0 +0,0 @@ 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/map/MapCanvas.java b/src/main/java/org/bukkit/map/MapCanvas.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/map/MapCanvas.java
+++ b/src/main/java/org/bukkit/map/MapCanvas.java
@@ -0,0 +0,0 @@ public interface MapCanvas {
      * @param x The x coordinate, from 0 to 127.
      * @param y The y coordinate, from 0 to 127.
      * @return The color. See {@link MapPalette}.
-     * @deprecated Magic value, use {@link #getPixelColor(int, int)}
+     * @deprecated use {@link #getPixelColor(int, int)}
      */
-    @Deprecated
+    @Deprecated(forRemoval = true, since = "1.20.2") // Paper
     public byte getPixel(int x, int y);
 
     /**
@@ -0,0 +0,0 @@ public interface MapCanvas {
      * @param x The x coordinate, from 0 to 127.
      * @param y The y coordinate, from 0 to 127.
      * @return The color. See {@link MapPalette}.
-     * @deprecated Magic value, use {@link #getBasePixelColor(int, int)}
+     * @deprecated use {@link #getBasePixelColor(int, int)}
      */
-    @Deprecated
+    @Deprecated(forRemoval = true, since = "1.20.2") // Paper
     public byte getBasePixel(int x, int y);
 
     /**
diff --git a/src/main/java/org/bukkit/map/MapCursor.java b/src/main/java/org/bukkit/map/MapCursor.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/map/MapCursor.java
+++ b/src/main/java/org/bukkit/map/MapCursor.java
@@ -0,0 +0,0 @@ public final class MapCursor {
      * Get the type of this cursor.
      *
      * @return The type (color/style) of the map cursor.
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     public byte getRawType() {
         return type;
     }
@@ -0,0 +0,0 @@ public final class MapCursor {
      * Set the type of this cursor.
      *
      * @param type The type (color/style) of the map cursor.
-     * @deprecated Magic value
+     * @deprecated use {@link #setType(Type)}
      */
-    @Deprecated
+    @Deprecated(forRemoval = true, since = "1.20.2") // Paper
     public void setRawType(byte type) {
         if (type < 0 || type > 26) {
             throw new IllegalArgumentException("Type must be in the range 0-26");
@@ -0,0 +0,0 @@ public final class MapCursor {
          * Gets the internal value of the cursor.
          *
          * @return the value
-         * @deprecated Magic value
+         * @apiNote Internal Use Only
          */
-        @Deprecated
+        @org.jetbrains.annotations.ApiStatus.Internal // Paper
         public byte getValue() {
             return value;
         }
@@ -0,0 +0,0 @@ public final class MapCursor {
          *
          * @param value the value
          * @return the matching type
-         * @deprecated Magic value
+         * @apiNote Internal Use Only
          */
-        @Deprecated
+        @org.jetbrains.annotations.ApiStatus.Internal // Paper
         @Nullable
         public static Type byValue(byte value) {
             for (Type t : values()) {
diff --git a/src/main/java/org/bukkit/map/MapPalette.java b/src/main/java/org/bukkit/map/MapPalette.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/map/MapPalette.java
+++ b/src/main/java/org/bukkit/map/MapPalette.java
@@ -0,0 +0,0 @@ public final class MapPalette {
      *
      * @param image The image to convert.
      * @return A byte[] containing the pixels of the image.
-     * @deprecated Magic value
+     * @deprecated use color-related methods
      */
-    @Deprecated
+    @Deprecated(forRemoval = true, since = "1.20.2") // Paper
     @NotNull
     public static byte[] imageToBytes(@NotNull Image image) {
         BufferedImage temp = new BufferedImage(image.getWidth(null), image.getHeight(null), BufferedImage.TYPE_INT_ARGB);
@@ -0,0 +0,0 @@ public final class MapPalette {
      * @param b The blue component of the color.
      * @param g The green component of the color.
      * @return The index in the palette.
-     * @deprecated Magic value
+     * @deprecated use color-related methods
      */
-    @Deprecated
+    @Deprecated(forRemoval = true, since = "1.20.2") // Paper
     public static byte matchColor(int r, int g, int b) {
         return matchColor(new Color(r, g, b));
     }
@@ -0,0 +0,0 @@ public final class MapPalette {
      *
      * @param color The Color to match.
      * @return The index in the palette.
-     * @deprecated Magic value
+     * @deprecated use color-related methods
      */
-    @Deprecated
+    @Deprecated(forRemoval = true, since = "1.20.2") // Paper
     public static byte matchColor(@NotNull Color color) {
         if (color.getAlpha() < 128) return 0;
 
@@ -0,0 +0,0 @@ public final class MapPalette {
      *
      * @param index The index in the palette.
      * @return The Color of the palette entry.
-     * @deprecated Magic value
+     * @deprecated use color directly
      */
-    @Deprecated
+    @Deprecated(forRemoval = true, since = "1.20.2") // Paper
     @NotNull
     public static Color getColor(byte index) {
         // Minecraft has 143 colors, some of which have negative byte representations
@@ -0,0 +0,0 @@ public final class MapPalette {
          * @param color The Color to match.
          * @return The index in the palette.
          * @throws IllegalStateException if {@link #isCached()} returns false
-         * @deprecated Magic value
+         * @apiNote Internal Use Only
          */
-        @Deprecated
+        @org.jetbrains.annotations.ApiStatus.Internal // Paper
         byte matchColor(@NotNull Color color);
     }
 }
diff --git a/src/main/java/org/bukkit/map/MapView.java b/src/main/java/org/bukkit/map/MapView.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/map/MapView.java
+++ b/src/main/java/org/bukkit/map/MapView.java
@@ -0,0 +0,0 @@ public interface MapView {
          *
          * @param value The raw scale
          * @return The enum scale, or null for an invalid input
-         * @deprecated Magic value
+         * @apiNote Internal Use Only
          */
-        @Deprecated
+        @org.jetbrains.annotations.ApiStatus.Internal // Paper
         @Nullable
         public static Scale valueOf(byte value) {
             switch (value) {
@@ -0,0 +0,0 @@ public interface MapView {
          * Get the raw value of this scale level.
          *
          * @return The scale value
-         * @deprecated Magic value
+         * @apiNote Internal Use Only
          */
-        @Deprecated
+        @org.jetbrains.annotations.ApiStatus.Internal // Paper
         public byte getValue() {
             return value;
         }
diff --git a/src/main/java/org/bukkit/material/Openable.java b/src/main/java/org/bukkit/material/Openable.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/material/Openable.java
+++ b/src/main/java/org/bukkit/material/Openable.java
@@ -0,0 +0,0 @@
 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/material/Redstone.java
+++ b/src/main/java/org/bukkit/material/Redstone.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/material/Step.java
+++ b/src/main/java/org/bukkit/material/Step.java
@@ -0,0 +0,0 @@ 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 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/material/types/MushroomBlockTexture.java
+++ b/src/main/java/org/bukkit/material/types/MushroomBlockTexture.java
@@ -0,0 +0,0 @@ import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents the different textured blocks of mushroom.
+ * @deprecated use BlockData
  */
+@Deprecated // Paper
 public enum MushroomBlockTexture {
 
     /**
diff --git a/src/main/java/org/bukkit/potion/PotionEffectType.java b/src/main/java/org/bukkit/potion/PotionEffectType.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/potion/PotionEffectType.java
+++ b/src/main/java/org/bukkit/potion/PotionEffectType.java
@@ -0,0 +0,0 @@ public abstract class PotionEffectType implements Keyed {
      * Returns the unique ID of this type.
      *
      * @return Unique ID
-     * @deprecated Magic value
+     * @deprecated use {@link #key()}
      */
-    @Deprecated
+    @Deprecated(forRemoval = true, since = "1.20.2") // Paper
     public abstract int getId();
 
     /**
@@ -0,0 +0,0 @@ public abstract class PotionEffectType implements Keyed {
      *
      * @param id Unique ID to fetch
      * @return Resulting type, or null if not found.
-     * @deprecated Magic value
+     * @apiNote Internal Use Only
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     @Nullable
     public static PotionEffectType getById(int id) {
         PotionEffectType type = ID_MAP.get(id);
diff --git a/src/test/java/org/bukkit/materials/MaterialDataTest.java b/src/test/java/org/bukkit/materials/MaterialDataTest.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/test/java/org/bukkit/materials/MaterialDataTest.java
+++ b/src/test/java/org/bukkit/materials/MaterialDataTest.java
@@ -0,0 +0,0 @@ import org.bukkit.material.WoodenStep;
 import org.bukkit.material.types.MushroomBlockTexture;
 import org.junit.jupiter.api.Test;
 
+@Deprecated // Paper
 public class MaterialDataTest {
 
     @Test