Fix javadoc errors/warnings

28 files changed, 79 insertions, 65 deletions

diff --git a/src/main/java/org/bukkit/EntityEffect.java b/src/main/java/org/bukkit/EntityEffect.java
index fbf21fb3..82d96f67 100644
--- a/src/main/java/org/bukkit/EntityEffect.java
+++ b/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 {@link EntityEffect} representing the given value, or null if
-     *         it doesn't exist
+     * @return The data value
      */
     public byte getData() {
         return data;
diff --git a/src/main/java/org/bukkit/Server.java b/src/main/java/org/bukkit/Server.java
index dc6e4aa5..cf3a592b 100644
--- a/src/main/java/org/bukkit/Server.java
+++ b/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);
diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
index 080d4153..daebf0bd 100644
--- a/src/main/java/org/bukkit/World.java
+++ b/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);
diff --git a/src/main/java/org/bukkit/WorldCreator.java b/src/main/java/org/bukkit/WorldCreator.java
index b48c1ad5..8bfbb262 100644
--- a/src/main/java/org/bukkit/WorldCreator.java
+++ b/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) {
diff --git a/src/main/java/org/bukkit/block/CreatureSpawner.java b/src/main/java/org/bukkit/block/CreatureSpawner.java
index 9e479a75..e54d9972 100644
--- a/src/main/java/org/bukkit/block/CreatureSpawner.java
+++ b/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);
diff --git a/src/main/java/org/bukkit/configuration/ConfigurationSection.java b/src/main/java/org/bukkit/configuration/ConfigurationSection.java
index 90d43849..f089c5df 100644
--- a/src/main/java/org/bukkit/configuration/ConfigurationSection.java
+++ b/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);
diff --git a/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerializable.java b/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerializable.java
index 53b4fb2f..d6035b8d 100644
--- a/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerializable.java
+++ b/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 "valueOf" that accepts a single {@link Map<String, Object>} and returns the class.</li>
- * <li>A constructor that accepts a single {@link Map<String, Object>}.</li>
+ * <li>A static method "deserialize" that accepts a single {@link Map}&lt;{@link String}, {@link Object}>
+ * and returns the class.</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 {
diff --git a/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerialization.java b/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerialization.java
index 6f630880..f2e7fe7f 100644
--- a/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerialization.java
+++ b/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;
diff --git a/src/main/java/org/bukkit/enchantments/Enchantment.java b/src/main/java/org/bukkit/enchantments/Enchantment.java
index 2ec48540..c6e744d7 100644
--- a/src/main/java/org/bukkit/enchantments/Enchantment.java
+++ b/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) {
diff --git a/src/main/java/org/bukkit/entity/Boat.java b/src/main/java/org/bukkit/entity/Boat.java
index c4f98400..c363a38f 100644
--- a/src/main/java/org/bukkit/entity/Boat.java
+++ b/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();
 
diff --git a/src/main/java/org/bukkit/entity/Entity.java b/src/main/java/org/bukkit/entity/Entity.java
index dc10fc4d..9d12cb78 100644
--- a/src/main/java/org/bukkit/entity/Entity.java
+++ b/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);
diff --git a/src/main/java/org/bukkit/entity/EntityType.java b/src/main/java/org/bukkit/entity/EntityType.java
index 420bccb0..53695e1c 100644
--- a/src/main/java/org/bukkit/entity/EntityType.java
+++ b/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
      */
diff --git a/src/main/java/org/bukkit/entity/LivingEntity.java b/src/main/java/org/bukkit/entity/LivingEntity.java
index e45fc721..3180b7d6 100644
--- a/src/main/java/org/bukkit/entity/LivingEntity.java
+++ b/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);
 
diff --git a/src/main/java/org/bukkit/entity/ThrownPotion.java b/src/main/java/org/bukkit/entity/ThrownPotion.java
index 4a858c6b..8e34ca21 100644
--- a/src/main/java/org/bukkit/entity/ThrownPotion.java
+++ b/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();
 }
diff --git a/src/main/java/org/bukkit/event/enchantment/EnchantItemEvent.java b/src/main/java/org/bukkit/event/enchantment/EnchantItemEvent.java
index 4b40d366..97cfe25b 100644
--- a/src/main/java/org/bukkit/event/enchantment/EnchantItemEvent.java
+++ b/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;
diff --git a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
index d97adf3b..9121db75 100644
--- a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
+++ b/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;
diff --git a/src/main/java/org/bukkit/event/entity/PlayerDeathEvent.java b/src/main/java/org/bukkit/event/entity/PlayerDeathEvent.java
index 26f75ed6..b773d6e5 100644
--- a/src/main/java/org/bukkit/event/entity/PlayerDeathEvent.java
+++ b/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;
diff --git a/src/main/java/org/bukkit/permissions/Permission.java b/src/main/java/org/bukkit/permissions/Permission.java
index abac6a9a..1feabfbf 100644
--- a/src/main/java/org/bukkit/permissions/Permission.java
+++ b/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
      */
diff --git a/src/main/java/org/bukkit/plugin/InvalidPluginException.java b/src/main/java/org/bukkit/plugin/InvalidPluginException.java
index ba1fc07e..1556ba52 100644
--- a/src/main/java/org/bukkit/plugin/InvalidPluginException.java
+++ b/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);
diff --git a/src/main/java/org/bukkit/plugin/PluginLogger.java b/src/main/java/org/bukkit/plugin/PluginLogger.java
index 21bbfa07..7fe89479 100644
--- a/src/main/java/org/bukkit/plugin/PluginLogger.java
+++ b/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
- * plugin doing the logging.
+ * The PluginLogger class is a modified {@link Logger} that prepends all logging calls with the name of the
+ * 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);
diff --git a/src/main/java/org/bukkit/plugin/PluginManager.java b/src/main/java/org/bukkit/plugin/PluginManager.java
index 98bcc0f3..804f4415 100644
--- a/src/main/java/org/bukkit/plugin/PluginManager.java
+++ b/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);
 
diff --git a/src/main/java/org/bukkit/plugin/RegisteredListener.java b/src/main/java/org/bukkit/plugin/RegisteredListener.java
index 5af42502..9dd0b7a1 100644
--- a/src/main/java/org/bukkit/plugin/RegisteredListener.java
+++ b/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){
diff --git a/src/main/java/org/bukkit/plugin/messaging/Messenger.java b/src/main/java/org/bukkit/plugin/messaging/Messenger.java
index 238643e9..c5b15250 100644
--- a/src/main/java/org/bukkit/plugin/messaging/Messenger.java
+++ b/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);
diff --git a/src/main/java/org/bukkit/potion/Potion.java b/src/main/java/org/bukkit/potion/Potion.java
index e9c8e041..18a03ae2 100644
--- a/src/main/java/org/bukkit/potion/Potion.java
+++ b/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
-     *            The itemstack to apply to
+     * @param 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
-     *            The entity to apply the effects to
+     * @param 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
-     *            Whether the potion should have extended duration
+     * @param isExtended 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
-     *            The new tier of this potion
+     * @param tier 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
-     *            The new level of this potion
+     * @param level 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
-     *            The amount of the ItemStack
+     * @param amount 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
-     *            The new PotionBrewer
+     * @param other The new PotionBrewer
      */
     public static void setPotionBrewer(PotionBrewer other) {
         if (brewer != null)
diff --git a/src/main/java/org/bukkit/potion/PotionBrewer.java b/src/main/java/org/bukkit/potion/PotionBrewer.java
index 14df6a05..7d8318cf 100644
--- a/src/main/java/org/bukkit/potion/PotionBrewer.java
+++ b/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
-     *            The type of potion
-     * @param duration
-     *            The duration in ticks
-     * @param amplifier
-     *            The amplifier of the effect
+     * @param potion The type of potion
+     * @param duration The duration in ticks
+     * @param amplifier The amplifier of the effect
+     * @return The resulting potion 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
-     *            The data value of the potion
-     * @return
+     * @param damage The data value of the potion
+     * @return The list of effects
      */
     public Collection<PotionEffect> getEffectsFromDamage(int damage);
 }
diff --git a/src/main/java/org/bukkit/potion/PotionEffect.java b/src/main/java/org/bukkit/potion/PotionEffect.java
index e4066323..6c738776 100644
--- a/src/main/java/org/bukkit/potion/PotionEffect.java
+++ b/src/main/java/org/bukkit/potion/PotionEffect.java
@@ -26,8 +26,8 @@ public class PotionEffect {
      * {@link LivingEntity}.
      *
      * @see LivingEntity#addPotionEffect(PotionEffect)
-     * @param entity
-     *            The entity to add this effect to
+     * @param entity 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;
diff --git a/src/main/java/org/bukkit/potion/PotionEffectType.java b/src/main/java/org/bukkit/potion/PotionEffectType.java
index 8a600556..388c6c28 100644
--- a/src/main/java/org/bukkit/potion/PotionEffectType.java
+++ b/src/main/java/org/bukkit/potion/PotionEffectType.java
@@ -86,7 +86,7 @@ public abstract class PotionEffectType {
     public static final PotionEffectType BLINDNESS = new PotionEffectTypeWrapper(15);
 
     /**
-     * Allows an entity to see in the dark. NOTE: Unusable due to not being 
+     * Allows an entity to see in the dark. NOTE: Unusable due to not being
      * implemented by Minecraft.
      */
     @Deprecated
@@ -180,8 +180,7 @@ public abstract class PotionEffectType {
     /**
      * Gets the effect type specified by the unique id.
      *
-     * @param id
-     *            Unique ID to fetch
+     * @param id 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
-     *            Name of PotionEffectType to fetch
+     * @param name 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
-     *            PotionType to register
+     * @param type PotionType to register
      */
     public static void registerPotionEffectType(PotionEffectType type) {
         if (byId[type.id] != null || byName.containsKey(type.getName().toLowerCase())) {
diff --git a/src/main/java/org/bukkit/potion/PotionEffectTypeWrapper.java b/src/main/java/org/bukkit/potion/PotionEffectTypeWrapper.java
index d1cc99f3..ec3f0a65 100644
--- a/src/main/java/org/bukkit/potion/PotionEffectTypeWrapper.java
+++ b/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());