Fix some javadoc warnings

Also remove a couple old/broken deprecated methods

By: md_5 <git@md-5.net>

paper-api/src/main/java/org/bukkit/Chunk.java

@@ -143,7 +143,7 @@ public interface Chunk {
      * <p>
      * A force loaded chunk will not be unloaded due to lack of player activity.
      *
-     * @param forced
+     * @param forced force load status
      * @see World#setChunkForceLoaded(int, int, boolean)
      */
     void setForceLoaded(boolean forced);

paper-api/src/main/java/org/bukkit/NamespacedKey.java

@@ -39,8 +39,8 @@ public final class NamespacedKey {
     /**
      * Create a key in a specific namespace.
      *
-     * @param namespace
-     * @param key
+     * @param namespace namespace
+     * @param key key
      * @deprecated should never be used by plugins, for internal use only!!
      */
     @Deprecated

paper-api/src/main/java/org/bukkit/World.java

@@ -309,7 +309,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      *
      * @param x X-coordinate of the chunk
      * @param z Z-coordinate of the chunk
-     * @param forced
+     * @param forced force load status
      */
     public void setChunkForceLoaded(int x, int z, boolean forced);
 
@@ -1624,6 +1624,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * Spawns the particle (the number of times specified by count)
      * at the target location.
      *
+     * @param <T> type of particle data (see {@link Particle#getDataType()}
      * @param particle the particle to spawn
      * @param location the location to spawn at
      * @param count the number of particles
@@ -1637,6 +1638,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * Spawns the particle (the number of times specified by count)
      * at the target location.
      *
+     * @param <T> type of particle data (see {@link Particle#getDataType()}
      * @param particle the particle to spawn
      * @param x the position on the x axis to spawn at
      * @param y the position on the y axis to spawn at
@@ -1685,6 +1687,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * randomized positively and negatively by the offset parameters
      * on each axis.
      *
+     * @param <T> type of particle data (see {@link Particle#getDataType()}
      * @param particle the particle to spawn
      * @param location the location to spawn at
      * @param count the number of particles
@@ -1702,6 +1705,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * randomized positively and negatively by the offset parameters
      * on each axis.
      *
+     * @param <T> type of particle data (see {@link Particle#getDataType()}
      * @param particle the particle to spawn
      * @param x the position on the x axis to spawn at
      * @param y the position on the y axis to spawn at
@@ -1757,6 +1761,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * randomized positively and negatively by the offset parameters
      * on each axis.
      *
+     * @param <T> type of particle data (see {@link Particle#getDataType()}
      * @param particle the particle to spawn
      * @param location the location to spawn at
      * @param count the number of particles
@@ -1776,6 +1781,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * randomized positively and negatively by the offset parameters
      * on each axis.
      *
+     * @param <T> type of particle data (see {@link Particle#getDataType()}
      * @param particle the particle to spawn
      * @param x the position on the x axis to spawn at
      * @param y the position on the y axis to spawn at
@@ -1797,6 +1803,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * randomized positively and negatively by the offset parameters
      * on each axis.
      *
+     * @param <T> type of particle data (see {@link Particle#getDataType()}
      * @param particle the particle to spawn
      * @param location the location to spawn at
      * @param count the number of particles
@@ -1819,6 +1826,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * randomized positively and negatively by the offset parameters
      * on each axis.
      *
+     * @param <T> type of particle data (see {@link Particle#getDataType()}
      * @param particle the particle to spawn
      * @param x the position on the x axis to spawn at
      * @param y the position on the y axis to spawn at

paper-api/src/main/java/org/bukkit/block/Campfire.java

@@ -34,35 +34,41 @@ public interface Campfire extends TileState {
     void setItem(int index, @Nullable ItemStack item);
 
     /**
-     * Get cook time.This is the amount of time the item has been cooking for.
+     * Get cook time.
      *
-     * @param index
+     * This is the amount of time the item has been cooking for.
+     *
+     * @param index item slot index
      * @return Cook time
      */
     int getCookTime(int index);
 
     /**
-     * Set cook time.This is the amount of time the item has been cooking for.
+     * Set cook time.
      *
-     * @param index
+     * This is the amount of time the item has been cooking for.
+     *
+     * @param index item slot index
      * @param cookTime Cook time
      */
     void setCookTime(int index, int cookTime);
 
     /**
-     * Get cook time total.This is the amount of time the item is required to
-     * cook for.
+     * Get cook time total.
      *
-     * @param index
+     * This is the amount of time the item is required to cook for.
+     *
+     * @param index item slot index
      * @return Cook time total
      */
     int getCookTimeTotal(int index);
 
     /**
-     * Set cook time.This is the amount of time the item is required to cook
-     * for.
+     * Set cook time.
      *
-     * @param index
+     * This is the amount of time the item is required to cook for.
+     *
+     * @param index item slot index
      * @param cookTimeTotal Cook time total
      */
     void setCookTimeTotal(int index, int cookTimeTotal);

paper-api/src/main/java/org/bukkit/entity/AbstractHorse.java

@@ -25,7 +25,7 @@ public interface AbstractHorse extends Animals, Vehicle, InventoryHolder, Tameab
     public Horse.Variant getVariant();
 
     /**
-     * @param variant
+     * @param variant variant
      * @deprecated you are required to spawn a different entity
      */
     @Deprecated

paper-api/src/main/java/org/bukkit/entity/AreaEffectCloud.java

@@ -138,6 +138,7 @@ public interface AreaEffectCloud extends Entity {
     /**
      * Sets the particle which this cloud will be composed of
      *
+     * @param <T> type of particle data (see {@link Particle#getDataType()}
      * @param particle the new particle type
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}

paper-api/src/main/java/org/bukkit/entity/Guardian.java

@@ -12,7 +12,7 @@ public interface Guardian extends Monster {
     public boolean isElder();
 
     /**
-     * @param shouldBeElder
+     * @param shouldBeElder shouldBeElder
      * @deprecated Must spawn a new {@link ElderGuardian}.
      */
     @Deprecated

paper-api/src/main/java/org/bukkit/entity/Horse.java

@@ -154,7 +154,7 @@ public interface Horse extends AbstractHorse {
     public boolean isCarryingChest();
 
     /**
-     * @param chest
+     * @param chest chest
      * @deprecated see {@link ChestedHorse}
      */
     @Deprecated

paper-api/src/main/java/org/bukkit/entity/Player.java

@@ -1258,6 +1258,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * Spawns the particle (the number of times specified by count)
      * at the target location.
      *
+     * @param <T> type of particle data (see {@link Particle#getDataType()}
      * @param particle the particle to spawn
      * @param location the location to spawn at
      * @param count the number of particles
@@ -1271,6 +1272,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * Spawns the particle (the number of times specified by count)
      * at the target location.
      *
+     * @param <T> type of particle data (see {@link Particle#getDataType()}
      * @param particle the particle to spawn
      * @param x the position on the x axis to spawn at
      * @param y the position on the y axis to spawn at
@@ -1319,6 +1321,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * randomized positively and negatively by the offset parameters
      * on each axis.
      *
+     * @param <T> type of particle data (see {@link Particle#getDataType()}
      * @param particle the particle to spawn
      * @param location the location to spawn at
      * @param count the number of particles
@@ -1336,6 +1339,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * randomized positively and negatively by the offset parameters
      * on each axis.
      *
+     * @param <T> type of particle data (see {@link Particle#getDataType()}
      * @param particle the particle to spawn
      * @param x the position on the x axis to spawn at
      * @param y the position on the y axis to spawn at
@@ -1391,6 +1395,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * randomized positively and negatively by the offset parameters
      * on each axis.
      *
+     * @param <T> type of particle data (see {@link Particle#getDataType()}
      * @param particle the particle to spawn
      * @param location the location to spawn at
      * @param count the number of particles
@@ -1410,6 +1415,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * randomized positively and negatively by the offset parameters
      * on each axis.
      *
+     * @param <T> type of particle data (see {@link Particle#getDataType()}
      * @param particle the particle to spawn
      * @param x the position on the x axis to spawn at
      * @param y the position on the y axis to spawn at

paper-api/src/main/java/org/bukkit/entity/Skeleton.java

@@ -19,6 +19,7 @@ public interface Skeleton extends Monster {
     public SkeletonType getSkeletonType();
 
     /**
+     * @param type type
      * @deprecated Must spawn a new subtype variant
      */
     @Deprecated

paper-api/src/main/java/org/bukkit/entity/Zombie.java

@@ -32,7 +32,7 @@ public interface Zombie extends Monster {
     public boolean isVillager();
 
     /**
-     * @param flag
+     * @param flag flag
      * @deprecated must spawn {@link ZombieVillager}.
      */
     @Deprecated
@@ -40,7 +40,7 @@ public interface Zombie extends Monster {
     public void setVillager(boolean flag);
 
     /**
-     * @param profession
+     * @param profession profession
      * @see ZombieVillager#getVillagerProfession()
      */
     @Deprecated

paper-api/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java

@@ -78,15 +78,6 @@ public class BlockDropItemEvent extends BlockEvent implements Cancellable {
         return items;
     }
 
-    /**
-     * @deprecated very temporary compatibility measure
-     */
-    @Deprecated
-    @NotNull
-    public Item getItem() {
-        return items.get(0);
-    }
-
     @Override
     public boolean isCancelled() {
         return cancel;

paper-api/src/main/java/org/bukkit/inventory/ItemFactory.java

@@ -132,10 +132,10 @@ public interface ItemFactory {
      * Apply a material change for an item meta. Do not use under any
      * circumstances.
      *
-     * @param meta
-     * @param material
+     * @param meta meta
+     * @param material material
      * @return updated material
-     * @throws IllegalArgumentException
+     * @throws IllegalArgumentException if bad material or data
      * @deprecated for internal use only
      */
     @Deprecated

paper-api/src/main/java/org/bukkit/inventory/Merchant.java

@@ -34,7 +34,7 @@ public interface Merchant {
      *
      * @param i the index
      * @return the recipe
-     * @throws IndexOutOfBoundsException
+     * @throws IndexOutOfBoundsException if recipe index out of bounds
      */
     @NotNull
     MerchantRecipe getRecipe(int i) throws IndexOutOfBoundsException;
@@ -44,7 +44,7 @@ public interface Merchant {
      *
      * @param i the index
      * @param recipe the recipe
-     * @throws IndexOutOfBoundsException
+     * @throws IndexOutOfBoundsException if recipe index out of bounds
      */
     void setRecipe(int i, @NotNull MerchantRecipe recipe) throws IndexOutOfBoundsException;
 

paper-api/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java

@@ -27,7 +27,7 @@ public interface CrossbowMeta extends ItemMeta {
      *
      * Removes all projectiles when given null.
      *
-     * @param projectiles
+     * @param projectiles the projectiles to set
      * @throws IllegalArgumentException if one of the projectiles is not an
      * arrow or firework rocket
      */

paper-api/src/main/java/org/bukkit/inventory/meta/ItemMeta.java

@@ -379,7 +379,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
     /**
      * Internal use only! Do not use under any circumstances!
      *
-     * @param version
+     * @param version version
      * @deprecated
      */
     @Deprecated

paper-api/src/main/java/org/bukkit/inventory/meta/tags/ItemTagType.java

@@ -11,7 +11,7 @@ import org.jetbrains.annotations.NotNull;
  * different complex types. This may be useful for the likes of a
  * UUIDItemTagType:
  * <pre>
- * <code>{@code
+ * {@code
  * public class UUIDItemTagType implements ItemTagType<byte[], UUID> {
  *
  *         {@literal @Override}
@@ -39,7 +39,7 @@ import org.jetbrains.annotations.NotNull;
  *             long secondLong = bb.getLong();
  *             return new UUID(firstLong, secondLong);
  *         }
- *     }}</code></pre>
+ *     }}</pre>
  *
  * @param <T> the primary object type that is stored in the given tag
  * @param <Z> the retrieved object type when applying this item tag type

paper-api/src/main/java/org/bukkit/persistence/PersistentDataType.java

@@ -10,7 +10,7 @@ import org.jetbrains.annotations.NotNull;
  * {@link PersistentDataType} with different complex types. This may be useful
  * for the likes of a UUIDTagType:
  * <pre>
- * <code>{@code
+ * {@code
  * public class UUIDTagType implements PersistentDataType<byte[], UUID> {
  *
  *         {@literal @Override}
@@ -38,7 +38,7 @@ import org.jetbrains.annotations.NotNull;
  *             long secondLong = bb.getLong();
  *             return new UUID(firstLong, secondLong);
  *         }
- *     }}</code></pre>
+ *     }}</pre>
  *
  * @param <T> the primary object type that is stored in the given tag
  * @param <Z> the retrieved object type when applying this tag type

paper-api/src/main/java/org/bukkit/potion/Potion.java

@@ -26,7 +26,6 @@ public class Potion {
      * water bottle.
      *
      * @param type The potion type
-     * @see #Potion(int)
      */
     public Potion(@NotNull PotionType type) {
         Validate.notNull(type, "Null PotionType");
@@ -77,14 +76,6 @@ public class Potion {
         this.extended = extended;
     }
 
-    /**
-     * @deprecated
-     */
-    @Deprecated
-    public Potion(int name) {
-        this(PotionType.WATER);
-    }
-
     /**
      * Chain this to the constructor to make the potion a splash potion.
      *

paper-api/src/main/java/org/bukkit/potion/PotionBrewer.java

@@ -37,6 +37,8 @@ public interface PotionBrewer {
      * a potion with the given type.
      *
      * @param type The type of the potion
+     * @param upgraded Whether the potion is upgraded
+     * @param extended Whether the potion is extended
      * @return The list of effects
      */
     @NotNull

paper-api/src/main/java/org/bukkit/potion/PotionType.java

@@ -1,6 +1,5 @@
 package org.bukkit.potion;
 
-import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.Nullable;
 
 /**
@@ -71,29 +70,13 @@ public enum PotionType {
         return extendable;
     }
 
-    /**
-     * @deprecated Non-functional
-     */
-    @Deprecated
-    public int getDamageValue() {
-        return this.ordinal();
-    }
-
     public int getMaxLevel() {
         return upgradeable ? 2 : 1;
     }
 
     /**
-     * @deprecated Non-functional
-     */
-    @Deprecated
-    @Nullable
-    @Contract("_ -> null")
-    public static PotionType getByDamageValue(int damage) {
-        return null;
-    }
-
-    /**
+     * @param effectType the effect to get by
+     * @return the matching potion type
      * @deprecated Misleading
      */
     @Deprecated