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.
2019-03-24 18:39:01 -04:00
parent ded424db46
commit 2825ece820
145 changed files with 372 additions and 235 deletions
--- a/paper-api/src/main/java/org/bukkit/entity/AbstractArrow.java
+++ b/paper-api/src/main/java/org/bukkit/entity/AbstractArrow.java
@@ -157,7 +157,7 @@ public interface AbstractArrow extends Projectile {
     *
     * @return The firing ItemStack
     */
-    @NotNull
+    @Nullable // Paper
    @ApiStatus.Experimental
    public ItemStack getWeapon();

--- a/paper-api/src/main/java/org/bukkit/entity/Enderman.java
+++ b/paper-api/src/main/java/org/bukkit/entity/Enderman.java
@@ -25,15 +25,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(forRemoval = true, since = "1.13")
    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(forRemoval = true, since = "1.13")
    public void setCarriedMaterial(@NotNull MaterialData material);

    /**
--- a/paper-api/src/main/java/org/bukkit/entity/EntityType.java
+++ b/paper-api/src/main/java/org/bukkit/entity/EntityType.java
@@ -417,9 +417,9 @@ 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(since = "1.6.2")
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
    @Contract("null -> null")
    @Nullable
    public static EntityType fromName(@Nullable String name) {
--- a/paper-api/src/main/java/org/bukkit/entity/ItemDisplay.java
+++ b/paper-api/src/main/java/org/bukkit/entity/ItemDisplay.java
@@ -14,7 +14,7 @@ public interface ItemDisplay extends Display {
     *
     * @return the displayed item stack
     */
-    @Nullable
+    @NotNull // Paper
    ItemStack getItemStack();

    /**
--- a/paper-api/src/main/java/org/bukkit/entity/LightningStrike.java
+++ b/paper-api/src/main/java/org/bukkit/entity/LightningStrike.java
@@ -84,6 +84,10 @@ public interface LightningStrike extends Entity {
    public void setCausingPlayer(@Nullable Player player);

    // Spigot start
+    /**
+     * @deprecated Unsupported api
+     */
+    @Deprecated // Paper
    public class Spigot extends Entity.Spigot {

        /**
@@ -98,8 +102,12 @@ public interface LightningStrike extends Entity {
        }
    }

+    /**
+     * @deprecated Unsupported api
+     */
    @NotNull
    @Override
+    @Deprecated // Paper
    Spigot spigot();
    // Spigot end
 }
--- a/paper-api/src/main/java/org/bukkit/entity/LingeringPotion.java
+++ b/paper-api/src/main/java/org/bukkit/entity/LingeringPotion.java
@@ -3,7 +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(since = "1.20.5")
+@Deprecated(since = "1.20.5", forRemoval = true) // Paper
 public interface LingeringPotion extends ThrownPotion { }
--- a/paper-api/src/main/java/org/bukkit/entity/LivingEntity.java
+++ b/paper-api/src/main/java/org/bukkit/entity/LivingEntity.java
@@ -716,7 +716,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);

    /**
@@ -981,7 +983,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
     * @deprecated entity groupings are now managed by tags, not categories
     */
    @NotNull
-    @Deprecated(since = "1.20.5")
+    @Deprecated(since = "1.20.5", forRemoval = true) @org.jetbrains.annotations.Contract("-> fail") // Paper
    public EntityCategory getCategory();

    /**
--- a/paper-api/src/main/java/org/bukkit/entity/Minecart.java
+++ b/paper-api/src/main/java/org/bukkit/entity/Minecart.java
@@ -102,7 +102,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(forRemoval = true, since = "1.13")
    public void setDisplayBlock(@Nullable MaterialData material);

    /**
@@ -110,8 +112,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(forRemoval = true, since = "1.13")
    public MaterialData getDisplayBlock();

    /**
--- a/paper-api/src/main/java/org/bukkit/entity/OminousItemSpawner.java
+++ b/paper-api/src/main/java/org/bukkit/entity/OminousItemSpawner.java
@@ -15,7 +15,7 @@ public interface OminousItemSpawner extends Entity {
     *
     * @return the item
     */
-    @Nullable
+    @org.jetbrains.annotations.NotNull // Paper
    ItemStack getItem();

    /**
--- a/paper-api/src/main/java/org/bukkit/entity/Player.java
+++ b/paper-api/src/main/java/org/bukkit/entity/Player.java
@@ -1680,11 +1680,8 @@ 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();

    /**
--- a/paper-api/src/main/java/org/bukkit/entity/Projectile.java
+++ b/paper-api/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(since = "1.20.2")
+    @Deprecated(since = "1.20.2", 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(since = "1.20.2")
+    @Deprecated(since = "1.20.2", forRemoval = true)
    public void setBounce(boolean doesBounce);
 }
--- a/paper-api/src/main/java/org/bukkit/entity/SplashPotion.java
+++ b/paper-api/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(since = "1.14")
+@Deprecated(since = "1.14", forRemoval = true) // Paper
 public interface SplashPotion extends ThrownPotion { }
--- a/paper-api/src/main/java/org/bukkit/entity/ZombieVillager.java
+++ b/paper-api/src/main/java/org/bukkit/entity/ZombieVillager.java
@@ -13,15 +13,15 @@ public interface ZombieVillager extends Zombie {
     * Sets the villager profession of this zombie.
     */
    @Override
-    void setVillagerProfession(@Nullable Villager.Profession profession);
+    void setVillagerProfession(@NotNull Villager.Profession profession); // Paper

    /**
     * Returns the villager profession of this zombie.
     *
-     * @return the profession or null
+     * @return the profession
     */
    @Override
-    @Nullable
+    @NotNull // Paper
    Villager.Profession getVillagerProfession();

    /**
--- a/paper-api/src/main/java/org/bukkit/entity/memory/MemoryKey.java
+++ b/paper-api/src/main/java/org/bukkit/entity/memory/MemoryKey.java
@@ -69,6 +69,12 @@ public final class MemoryKey<T> implements Keyed {
    public static final MemoryKey<Location> LIKED_NOTEBLOCK_POSITION = new MemoryKey<>(NamespacedKey.minecraft("liked_noteblock"), Location.class);
    public static final MemoryKey<Integer> LIKED_NOTEBLOCK_COOLDOWN_TICKS = new MemoryKey<>(NamespacedKey.minecraft("liked_noteblock_cooldown_ticks"), Integer.class);
    public static final MemoryKey<Integer> ITEM_PICKUP_COOLDOWN_TICKS = new MemoryKey<>(NamespacedKey.minecraft("item_pickup_cooldown_ticks"), Integer.class);
+    /**
+     * @deprecated this constant uses the wrong generic type, the sniffer now stores different positions
+     * from possibly different worlds. Use the relevant methods in {@link org.bukkit.entity.Sniffer} directly
+     * for now.
+     */
+    @Deprecated // Paper
    public static final MemoryKey<Location> SNIFFER_EXPLORED_POSITIONS = new MemoryKey<>(NamespacedKey.minecraft("sniffer_explored_positions"), Location.class);

    /**