Fix javadoc errors/warnings

By: Celtic Minstrel <celtic.minstrel.ca@some.place>

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

@@ -55,11 +55,9 @@ public enum EntityEffect {
     }
 
     /**
-     * Gets the EntityEffect with the given data value
+     * Gets the data value of this EntityEffect
      *
-     * @param data Data value to fetch
+     * @return The data value
-     * @return The {@link EntityEffect} representing the given value, or null if
-     *         it doesn't exist
      */
     public byte getData() {
         return data;

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

@@ -286,7 +286,7 @@ public interface Server extends PluginMessageRecipient {
      * If the world is already loaded, it will just return the equivalent of
      * getWorld(creator.name()).
      *
-     * @param options Options to use when creating the world
+     * @param creator The options to use when creating the world.
      * @return Newly created or loaded world
      */
     public World createWorld(WorldCreator creator);

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

@@ -356,6 +356,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
     /**
      * Get a collection of all entities in this World matching the given class/interface
      *
+     * @param classes The classes representing the types of entity to match
      * @return A List of all Entities currently residing in this world that match the given class/interface
      */
     @Deprecated
@@ -364,6 +365,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
     /**
      * Get a collection of all entities in this World matching the given class/interface
      *
+     * @param cls The class representing the type of entity to match
      * @return A List of all Entities currently residing in this world that match the given class/interface
      */
     public <T extends Entity> Collection<T> getEntitiesByClass(Class<T> cls);
@@ -371,6 +373,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
     /**
      * Get a collection of all entities in this World matching any of the given classes/interfaces
      *
+     * @param classes The classes representing the types of entity to match
      * @return A List of all Entities currently residing in this world that match one or more of the given classes/interfaces
      */
     public Collection<Entity> getEntitiesByClasses(Class<?>... classes);

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

@@ -156,7 +156,7 @@ public class WorldCreator {
      * This may be null, in which case the "natural" generator for this environment
      * will be used.
      *
-     * @param env Chunk generator
+     * @param generator Chunk generator
      * @return This object, for chaining
      */
     public WorldCreator generator(ChunkGenerator generator) {
@@ -205,6 +205,7 @@ public class WorldCreator {
     /**
      * Sets whether or not worlds created or loaded with this creator will have structures.
      *
+     * @param generate Whether to generate structures
      * @return This object, for chaining
      */
     public WorldCreator generateStructures(boolean generate) {

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

@@ -35,7 +35,7 @@ public interface CreatureSpawner extends BlockState {
      * Set the spawner creature type.
      *
      * @param creatureType The creature type.
-     * @deprecated In favour of {@link #setSpawnedType(EntityType}.
+     * @deprecated In favour of {@link #setSpawnedType(EntityType)}.
      */
     @Deprecated
     public void setCreatureType(CreatureType creatureType);

paper-api/src/main/java/org/bukkit/configuration/ConfigurationSection.java

@@ -134,6 +134,7 @@ public interface ConfigurationSection {
      * regardless of if a default has been identified in the root {@link Configuration}.
      *
      * @param path Path of the Object to get.
+     * @param def The default value to return if the path is not found.
      * @return Requested Object.
      */
     public Object get(String path, Object def);
@@ -172,6 +173,7 @@ public interface ConfigurationSection {
      * previous value was itself a {@link ConfigurationSection}, it will be orphaned.
      *
      * @param path Path to create the section at.
+     * @param map The values to used.
      * @return Newly created section
      */
     public ConfigurationSection createSection(String path, Map<?, ?> map);
@@ -196,6 +198,7 @@ public interface ConfigurationSection {
      * regardless of if a default has been identified in the root {@link Configuration}.
      *
      * @param path Path of the String to get.
+     * @param def The default value to return if the path is not found or is not a String.
      * @return Requested String.
      */
     public String getString(String path, String def);
@@ -232,6 +235,7 @@ public interface ConfigurationSection {
      * regardless of if a default has been identified in the root {@link Configuration}.
      *
      * @param path Path of the int to get.
+     * @param def The default value to return if the path is not found or is not an int.
      * @return Requested int.
      */
     public int getInt(String path, int def);
@@ -268,6 +272,7 @@ public interface ConfigurationSection {
      * regardless of if a default has been identified in the root {@link Configuration}.
      *
      * @param path Path of the boolean to get.
+     * @param def The default value to return if the path is not found or is not a boolean.
      * @return Requested boolean.
      */
     public boolean getBoolean(String path, boolean def);
@@ -304,6 +309,7 @@ public interface ConfigurationSection {
      * regardless of if a default has been identified in the root {@link Configuration}.
      *
      * @param path Path of the double to get.
+     * @param def The default value to return if the path is not found or is not a double.
      * @return Requested double.
      */
     public double getDouble(String path, double def);
@@ -340,6 +346,7 @@ public interface ConfigurationSection {
      * regardless of if a default has been identified in the root {@link Configuration}.
      *
      * @param path Path of the long to get.
+     * @param def The default value to return if the path is not found or is not a long.
      * @return Requested long.
      */
     public long getLong(String path, long def);
@@ -377,6 +384,7 @@ public interface ConfigurationSection {
      * regardless of if a default has been identified in the root {@link Configuration}.
      *
      * @param path Path of the List to get.
+     * @param def The default value to return if the path is not found or is not a List.
      * @return Requested List.
      */
     public List<?> getList(String path, List<?> def);
@@ -558,12 +566,13 @@ public interface ConfigurationSection {
     public Vector getVector(String path);
 
     /**
-     * Gets the requested Vector by path, returning a default value if not found.
+     * Gets the requested {@link Vector} by path, returning a default value if not found.
      * <p>
      * If the Vector does not exist then the specified default value will returned
      * regardless of if a default has been identified in the root {@link Configuration}.
      *
      * @param path Path of the Vector to get.
+     * @param def The default value to return if the path is not found or is not a Vector.
      * @return Requested Vector.
      */
     public Vector getVector(String path, Vector def);
@@ -594,12 +603,13 @@ public interface ConfigurationSection {
     public OfflinePlayer getOfflinePlayer(String path);
 
     /**
-     * Gets the requested OfflinePlayer by path, returning a default value if not found.
+     * Gets the requested {@link OfflinePlayer} by path, returning a default value if not found.
      * <p>
      * If the OfflinePlayer does not exist then the specified default value will returned
      * regardless of if a default has been identified in the root {@link Configuration}.
      *
      * @param path Path of the OfflinePlayer to get.
+     * @param def The default value to return if the path is not found or is not an OfflinePlayer.
      * @return Requested OfflinePlayer.
      */
     public OfflinePlayer getOfflinePlayer(String path, OfflinePlayer def);
@@ -630,12 +640,13 @@ public interface ConfigurationSection {
     public ItemStack getItemStack(String path);
 
     /**
-     * Gets the requested ItemStack by path, returning a default value if not found.
+     * Gets the requested {@link ItemStack} by path, returning a default value if not found.
      * <p>
      * If the ItemStack does not exist then the specified default value will returned
      * regardless of if a default has been identified in the root {@link Configuration}.
      *
      * @param path Path of the ItemStack to get.
+     * @param def The default value to return if the path is not found or is not an ItemStack.
      * @return Requested ItemStack.
      */
     public ItemStack getItemStack(String path, ItemStack def);

paper-api/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerializable.java

@@ -8,9 +8,11 @@ import java.util.Map;
  * These objects MUST implement one of the following, in addition to the methods
  * as defined by this interface:
  * <ul>
- * <li>A static method "deserialize" that accepts a single {@link Map<String, Object>} and returns the class.</li>
+ * <li>A static method "deserialize" that accepts a single {@link Map}&lt;{@link String}, {@link Object}>
- * <li>A static method "valueOf" that accepts a single {@link Map<String, Object>} and returns the class.</li>
+ * and returns the class.</li>
- * <li>A constructor that accepts a single {@link Map<String, Object>}.</li>
+ * <li>A static method "valueOf" that accepts a single {@link Map}&lt;{@link String}, {@link Object}>
+ * and returns the class.</li>
+ * <li>A constructor that accepts a single {@link Map}&lt;{@link String}, {@link Object}>.</li>
  * </ul>
  */
 public interface ConfigurationSerializable {

paper-api/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerialization.java

@@ -8,6 +8,8 @@ import java.util.HashMap;
 import java.util.Map;
 import java.util.logging.Level;
 import java.util.logging.Logger;
+
+import org.bukkit.configuration.Configuration;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.util.BlockVector;
 import org.bukkit.util.Vector;

paper-api/src/main/java/org/bukkit/enchantments/Enchantment.java

@@ -197,7 +197,6 @@ public abstract class Enchantment {
      * <p>
      * Generally not to be used from within a plugin.
      *
-     * @param id ID of the enchantment
      * @param enchantment Enchantment to register
      */
     public static void registerEnchantment(Enchantment enchantment) {

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

@@ -23,7 +23,7 @@ public interface Boat extends Vehicle {
      * Gets the deceleration rate (newSpeed = curSpeed * rate) of occupied
      * boats. The default is 0.2.
      *
-     * @return
+     * @return The rate of deceleration
      */
     public double getOccupiedDeceleration();
 
@@ -32,7 +32,7 @@ public interface Boat extends Vehicle {
      * boats. Setting this to a higher value allows for quicker acceleration.
      * The default is 0.2.
      *
-     * @param speed deceleration rate
+     * @param rate deceleration rate
      */
     public void setOccupiedDeceleration(double rate);
 
@@ -41,7 +41,7 @@ public interface Boat extends Vehicle {
      * boats. The default is -1. Values below 0 indicate that no additional
      * deceleration is imposed.
      *
-     * @return
+     * @return The rate of deceleration
      */
     public double getUnoccupiedDeceleration();
 

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

@@ -57,7 +57,7 @@ public interface Entity extends Metadatable {
      * Teleports this entity to the given location
      *
      * @param location New location to teleport this entity to
-     * @praram cause The cause of this teleportation
+     * @param cause The cause of this teleportation
      * @return <code>true</code> if the teleport was successful
      */
     public boolean teleport(Location location, TeleportCause cause);
@@ -74,7 +74,7 @@ public interface Entity extends Metadatable {
      * Teleports this entity to the target Entity
      *
      * @param destination Entity to teleport this entity to
-     * @praram cause The cause of this teleportation
+     * @param cause The cause of this teleportation
      * @return <code>true</code> if the teleport was successful
      */
     public boolean teleport(Entity destination, TeleportCause cause);

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

@@ -3,6 +3,7 @@ package org.bukkit.entity;
 import java.util.HashMap;
 import java.util.Map;
 
+import org.bukkit.Location;
 import org.bukkit.World;
 
 public enum EntityType {
@@ -120,7 +121,8 @@ public enum EntityType {
     }
 
     /**
-     * Some entities cannot be spawned using {@link World#spawn(org.bukkit.Location, EntityType)}, usually
+     * Some entities cannot be spawned using {@link World#spawnCreature(Location, EntityType)}
+     * or {@link World#spawn(Location, Class)}, usually
      * because they require additional information in order to spawn.
      * @return False if the entity type cannot be spawned
      */

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

@@ -252,6 +252,7 @@ public interface LivingEntity extends Entity {
      * effect of the given {@link PotionEffectType} applied to it.
      *
      * @param type The potion type to check
+     * @return Whether the player has this potion effect active on them.
      */
     public boolean hasPotionEffect(PotionEffectType type);
 

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

@@ -10,6 +10,7 @@ import org.bukkit.potion.PotionEffect;
 public interface ThrownPotion extends Projectile {
     /**
      * Returns the effects that are applied by this potion.
+     * @return The potion effects
      */
     public Collection<PotionEffect> getEffects();
 }

paper-api/src/main/java/org/bukkit/event/enchantment/EnchantItemEvent.java

@@ -39,7 +39,7 @@ public class EnchantItemEvent extends InventoryEvent implements Cancellable {
     /**
      * Gets the player enchanting the item
      *
-     * @returns enchanting player
+     * @return enchanting player
      */
     public Player getEnchanter() {
         return enchanter;

paper-api/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java

@@ -33,7 +33,7 @@ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellab
     /**
      * Gets the player enchanting the item
      *
-     * @returns enchanting player
+     * @return enchanting player
      */
     public Player getEnchanter() {
         return enchanter;

paper-api/src/main/java/org/bukkit/event/entity/PlayerDeathEvent.java

@@ -72,7 +72,7 @@ public class PlayerDeathEvent extends EntityDeathEvent {
      * This does not indicate how much EXP should be dropped, please see
      * {@link #setDroppedExp(int)} for that.
      *
-     * @get exp New EXP of the respawned player
+     * @param exp New EXP of the respawned player
      */
     public void setNewExp(int exp) {
         newExp = exp;
@@ -90,7 +90,7 @@ public class PlayerDeathEvent extends EntityDeathEvent {
     /**
      * Sets the Level the Player should have at respawn.
      *
-     * @get level New Level of the respawned player
+     * @param level New Level of the respawned player
      */
     public void setNewLevel(int level) {
         newLevel = level;
@@ -108,7 +108,7 @@ public class PlayerDeathEvent extends EntityDeathEvent {
     /**
      * Sets the Total EXP the Player should have at respawn.
      *
-     * @get totalExp New Total EXP of the respawned player
+     * @param totalExp New Total EXP of the respawned player
      */
     public void setNewTotalExp(int totalExp) {
         newTotalExp = totalExp;

paper-api/src/main/java/org/bukkit/permissions/Permission.java

@@ -203,6 +203,7 @@ public class Permission {
      * description: Short string containing a very small description of this description. If not specified, empty string.
      *
      * @param data Map of permissions
+     * @param error An error message to show if a permission is invalid.
      * @param def Default permission value to use if missing
      * @return Permission object
      */

paper-api/src/main/java/org/bukkit/plugin/InvalidPluginException.java

@@ -35,7 +35,7 @@ public class InvalidPluginException extends Exception {
     /**
      * Constructs a new InvalidPluginException with the specified detail message
      *
-     * @param the detail message. The detail message is saved for later retrieval by the getMessage() method.
+     * @param message TThe detail message is saved for later retrieval by the getMessage() method.
      */
     public InvalidPluginException(final String message) {
         super(message);

paper-api/src/main/java/org/bukkit/plugin/PluginLogger.java

@@ -5,17 +5,17 @@ import java.util.logging.LogRecord;
 import java.util.logging.Logger;
 
 /**
- * The PluginLogger class is a modified {@link java.util.logging.Logger} that prepends all logging calls with the name of the
+ * The PluginLogger class is a modified {@link Logger} that prepends all logging calls with the name of the
- * plugin doing the logging.
+ * plugin doing the logging. The API for PluginLogger is exactly the same as {@link Logger}.
  *
- * The API for PluginLogger is exactly the same as {@link java.util.logging.Logger}.
+ * @see Logger
  */
 public class PluginLogger extends Logger {
     private String pluginName;
 
     /**
      * Creates a new PluginLogger that extracts the name from a plugin.
-     * @param context
+     * @param context A reference to the plugin
      */
     public PluginLogger(Plugin context) {
         super(context.getClass().getCanonicalName(), null);

paper-api/src/main/java/org/bukkit/plugin/PluginManager.java

@@ -92,7 +92,6 @@ public interface PluginManager {
      * Calls an event with the given details
      *
      * @param event Event details
-     * @return Called event
      */
     public void callEvent(Event event);
 

paper-api/src/main/java/org/bukkit/plugin/RegisteredListener.java

@@ -51,6 +51,7 @@ public class RegisteredListener {
      * Calls the event executor
      *
      * @param event The event
+     * @throws EventException If an event handler throws an exception.
      */
     public void callEvent(final Event event) throws EventException {
         if (event instanceof Cancellable){

paper-api/src/main/java/org/bukkit/plugin/messaging/Messenger.java

@@ -64,7 +64,7 @@ public interface Messenger {
      * @param plugin Plugin that wishes to register to this channel.
      * @param channel Channel to register.
      * @param listener Listener to receive messages on.
-     * @returns The resulting registration that was made as a result of this method.
+     * @return The resulting registration that was made as a result of this method.
      * @throws IllegalArgumentException Thrown if plugin, channel or listener is null, or the listener is already registered for this channel.
      */
     public PluginMessageListenerRegistration registerIncomingPluginChannel(Plugin plugin, String channel, PluginMessageListener listener);

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

@@ -34,6 +34,7 @@ public class Potion {
     }
 
     /** @deprecated In favour of {@link #Potion(PotionType, int)} */
+    @SuppressWarnings("javadoc")
     @Deprecated
     public Potion(PotionType type, Tier tier) {
         this(type, tier == Tier.TWO ? 2 : 1);
@@ -41,12 +42,14 @@ public class Potion {
     }
 
     /** @deprecated In favour of {@link #Potion(PotionType, int, boolean)} */
+    @SuppressWarnings("javadoc")
     @Deprecated
     public Potion(PotionType type, Tier tier, boolean splash) {
         this(type, tier == Tier.TWO ? 2 : 1, splash);
     }
 
     /** @deprecated In favour of {@link #Potion(PotionType, int, boolean, boolean)} */
+    @SuppressWarnings("javadoc")
     @Deprecated
     public Potion(PotionType type, Tier tier, boolean splash, boolean extended) {
         this(type, tier, splash);
@@ -85,7 +88,7 @@ public class Potion {
      * @param level The potion's level.
      * @param splash Whether it is a splash potion.
      * @param extended Whether it has an extended duration.
-     * @deprecated In favour of using {@link #Potion(PotionType)} with {@link #extended}
+     * @deprecated In favour of using {@link #Potion(PotionType)} with {@link #extend()}
      * and possibly {@link #splash()}.
      */
     @Deprecated
@@ -129,8 +132,7 @@ public class Potion {
      * Applies the effects of this potion to the given {@link ItemStack}. The
      * itemstack must be a potion.
      *
-     * @param to
+     * @param to The itemstack to apply to
-     *            The itemstack to apply to
      */
     public void apply(ItemStack to) {
         Validate.notNull(to, "itemstack cannot be null");
@@ -143,8 +145,7 @@ public class Potion {
      * {@link LivingEntity}.
      *
      * @see LivingEntity#addPotionEffects(Collection)
-     * @param to
+     * @param to The entity to apply the effects to
-     *            The entity to apply the effects to
      */
     public void apply(LivingEntity to) {
         Validate.notNull(to, "entity cannot be null");
@@ -236,8 +237,7 @@ public class Potion {
      * Set whether this potion has extended duration. This will cause the potion
      * to have roughly 8/3 more duration than a regular potion.
      *
-     * @param isExtended
+     * @param isExtended Whether the potion should have extended duration
-     *            Whether the potion should have extended duration
      */
     public void setHasExtendedDuration(boolean isExtended) {
         Validate.isTrue(type == null || !type.isInstant(), "Instant potions cannot be extended");
@@ -258,8 +258,7 @@ public class Potion {
     /**
      * Sets the {@link Tier} of this potion.
      *
-     * @param tier
+     * @param tier The new tier of this potion
-     *            The new tier of this potion
      * @deprecated In favour of {@link #setLevel(int)}
      */
     @Deprecated
@@ -281,8 +280,7 @@ public class Potion {
     /**
      * Sets the level of this potion.
      *
-     * @param level
+     * @param level The new level of this potion
-     *            The new level of this potion
      */
     public void setLevel(int level) {
         Validate.notNull(this.type, "No-effect potions don't have a level.");
@@ -322,8 +320,7 @@ public class Potion {
      * Converts this potion to an {@link ItemStack} with the specified amount
      * and a correct damage value.
      *
-     * @param amount
+     * @param amount The amount of the ItemStack
-     *            The amount of the ItemStack
      * @return The created ItemStack
      */
     public ItemStack toItemStack(int amount) {
@@ -402,8 +399,7 @@ public class Potion {
      * Sets the current instance of {@link PotionBrewer}. Generally not to be
      * used from within a plugin.
      *
-     * @param other
+     * @param other The new PotionBrewer
-     *            The new PotionBrewer
      */
     public static void setPotionBrewer(PotionBrewer other) {
         if (brewer != null)

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

@@ -10,12 +10,10 @@ public interface PotionBrewer {
      * Creates a {@link PotionEffect} from the given {@link PotionEffectType},
      * applying duration modifiers and checks.
      *
-     * @param potion
+     * @param potion The type of potion
-     *            The type of potion
+     * @param duration The duration in ticks
-     * @param duration
+     * @param amplifier The amplifier of the effect
-     *            The duration in ticks
+     * @return The resulting potion effect
-     * @param amplifier
-     *            The amplifier of the effect
      */
     public PotionEffect createEffect(PotionEffectType potion, int duration, int amplifier);
 
@@ -23,9 +21,8 @@ public interface PotionBrewer {
      * Returns a collection of {@link PotionEffect} that would be applied from a
      * potion with the given data value.
      *
-     * @param damage
+     * @param damage The data value of the potion
-     *            The data value of the potion
+     * @return The list of effects
-     * @return
      */
     public Collection<PotionEffect> getEffectsFromDamage(int damage);
 }

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

@@ -26,8 +26,8 @@ public class PotionEffect {
      * {@link LivingEntity}.
      *
      * @see LivingEntity#addPotionEffect(PotionEffect)
-     * @param entity
+     * @param entity The entity to add this effect to
-     *            The entity to add this effect to
+     * @return Whether the effect could be added
      */
     public boolean apply(LivingEntity entity) {
         return entity.addPotionEffect(this);
@@ -56,6 +56,7 @@ public class PotionEffect {
      * Returns the amplifier of this effect. A higher amplifier means the potion
      * effect happens more often over its duration and in some cases has more
      * effect on its target.
+     * @return The effect amplifier
      */
     public int getAmplifier() {
         return amplifier;
@@ -64,6 +65,7 @@ public class PotionEffect {
     /**
      * Returns the duration (in ticks) that this effect will run for when
      * applied to a {@link LivingEntity}.
+     * @return The duration of the effect
      */
     public int getDuration() {
         return duration;

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

@@ -180,8 +180,7 @@ public abstract class PotionEffectType {
     /**
      * Gets the effect type specified by the unique id.
      *
-     * @param id
+     * @param id Unique ID to fetch
-     *            Unique ID to fetch
      * @return Resulting type, or null if not found.
      */
     public static PotionEffectType getById(int id) {
@@ -193,8 +192,7 @@ public abstract class PotionEffectType {
     /**
      * Gets the effect type specified by the given name.
      *
-     * @param name
+     * @param name Name of PotionEffectType to fetch
-     *            Name of PotionEffectType to fetch
      * @return Resulting PotionEffectType, or null if not found.
      */
     public static PotionEffectType getByName(String name) {
@@ -207,8 +205,7 @@ public abstract class PotionEffectType {
      * <p>
      * Generally not to be used from within a plugin.
      *
-     * @param potionType
+     * @param type PotionType to register
-     *            PotionType to register
      */
     public static void registerPotionEffectType(PotionEffectType type) {
         if (byId[type.id] != null || byName.containsKey(type.getName().toLowerCase())) {

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

@@ -17,6 +17,7 @@ public class PotionEffectTypeWrapper extends PotionEffectType {
 
     /**
      * Get the potion type bound to this wrapper.
+     * @return The potion effect type
      */
     public PotionEffectType getType() {
         return PotionEffectType.getById(getId());