Pulling all pending Bukkit-JavaDoc changes

61 files changed, 219 insertions, 43 deletions

diff --git a/src/main/java/org/bukkit/OfflinePlayer.java b/src/main/java/org/bukkit/OfflinePlayer.java
index 013dc0a2..bf6682bb 100644
--- a/src/main/java/org/bukkit/OfflinePlayer.java
+++ b/src/main/java/org/bukkit/OfflinePlayer.java
@@ -6,6 +6,7 @@ import org.bukkit.entity.Player;
 import org.bukkit.permissions.ServerOperator;
 
 public interface OfflinePlayer extends ServerOperator, AnimalTamer, ConfigurationSerializable {
+
     /**
      * Checks if this player is currently online
      *
diff --git a/src/main/java/org/bukkit/Rotation.java b/src/main/java/org/bukkit/Rotation.java
index 02447745..90df0097 100644
--- a/src/main/java/org/bukkit/Rotation.java
+++ b/src/main/java/org/bukkit/Rotation.java
@@ -5,6 +5,7 @@ package org.bukkit;
  * It represents how something is viewed, as opposed to cardinal directions.
  */
 public enum Rotation {
+
     /**
      * No rotation
      */
diff --git a/src/main/java/org/bukkit/TravelAgent.java b/src/main/java/org/bukkit/TravelAgent.java
index 5a545fc7..2dfeffa8 100644
--- a/src/main/java/org/bukkit/TravelAgent.java
+++ b/src/main/java/org/bukkit/TravelAgent.java
@@ -1,72 +1,94 @@
 package org.bukkit;
 
+/**
+ * The Travel Agent handles the creation and the research of Nether and End
+ * portals when Entities try to use one.
+ * <p>
+ * It is used in {@link org.bukkit.event.entity.EntityPortalEvent} and in
+ * {@link org.bukkit.event.player.PlayerPortalEvent} to help developers
+ * reproduce and/or modify Vanilla behaviour.
+ */
 public interface TravelAgent {
 
     /**
      * Set the Block radius to search in for available portals.
      *
-     * @param radius The radius in which to search for a portal from the location.
-     * @return This travel agent.
+     * @param radius the radius in which to search for a portal from the
+     *     location
+     * @return this travel agent
      */
     public TravelAgent setSearchRadius(int radius);
 
     /**
      * Gets the search radius value for finding an available portal.
      *
-     * @return Returns the currently set search radius.
+     * @return the currently set search radius
      */
     public int getSearchRadius();
 
     /**
      * Sets the maximum radius from the given location to create a portal.
      *
-     * @param radius The radius in which to create a portal from the location.
-     * @return This travel agent.
+     * @param radius the radius in which to create a portal from the location
+     * @return this travel agent
      */
     public TravelAgent setCreationRadius(int radius);
 
     /**
      * Gets the maximum radius from the given location to create a portal.
      *
-     * @return Returns the currently set creation radius.
+     * @return the currently set creation radius
      */
     public int getCreationRadius();
 
     /**
-     * Returns whether the TravelAgent will attempt to create a destination portal or not.
+     * Returns whether the TravelAgent will attempt to create a destination
+     * portal or not.
      *
-     * @return Return whether the TravelAgent should create a destination portal or not.
+     * @return whether the TravelAgent should create a destination portal or
+     *     not
      */
     public boolean getCanCreatePortal();
 
     /**
-     * Sets whether the TravelAgent should attempt to create a destination portal or not.
+     * Sets whether the TravelAgent should attempt to create a destination
+     * portal or not.
      *
-     * @param create Sets whether the TravelAgent should create a destination portal or not.
+     * @param create Sets whether the TravelAgent should create a destination
+     *     portal or not
      */
     public void setCanCreatePortal(boolean create);
 
     /**
-     * Attempt to find a portal near the given location, if a portal is not found it will attempt to create one.
+     * Attempt to find a portal near the given location, if a portal is not
+     * found it will attempt to create one.
      *
-     * @param location The location where the search for a portal should begin.
-     * @return Returns the location of a portal which has been found or returns the location passed to the method if unsuccessful.
+     * @param location the location where the search for a portal should begin
+     * @return the location of a portal which has been found or returns the
+     *     location passed to the method if unsuccessful
+     * @see #createPortal(Location)
      */
     public Location findOrCreate(Location location);
 
     /**
      * Attempt to find a portal near the given location.
      *
-     * @param location The desired location of the portal.
-     * @return Returns the location of the nearest portal to the location.
+     * @param location the desired location of the portal
+     * @return the location of the nearest portal to the location
      */
     public Location findPortal(Location location);
 
     /**
      * Attempt to create a portal near the given location.
+     * <p>
+     * In the case of a Nether portal teleportation, this will attempt to
+     * create a Nether portal.
+     * <p>
+     * In the case of an Ender portal teleportation, this will (re-)create the
+     * obsidian platform and clean blocks above it.
      *
-     * @param location The desired location of the portal.
-     * @return True if a nether portal was successfully created.
+     * @param location the desired location of the portal
+     * @return true if a portal was successfully created
      */
     public boolean createPortal(Location location);
-}
\ No newline at end of file
+}
diff --git a/src/main/java/org/bukkit/TreeType.java b/src/main/java/org/bukkit/TreeType.java
index 93a729f9..8945e4c9 100644
--- a/src/main/java/org/bukkit/TreeType.java
+++ b/src/main/java/org/bukkit/TreeType.java
@@ -4,6 +4,7 @@ package org.bukkit;
  * Tree and organic structure types.
  */
 public enum TreeType {
+
     /**
      * Regular tree, no branches
      */
diff --git a/src/main/java/org/bukkit/Warning.java b/src/main/java/org/bukkit/Warning.java
index e4187a9a..fca77cec 100644
--- a/src/main/java/org/bukkit/Warning.java
+++ b/src/main/java/org/bukkit/Warning.java
@@ -20,6 +20,7 @@ public @interface Warning {
      * This represents the states that server verbose for warnings may be.
      */
     public enum WarningState {
+
         /**
          * Indicates all warnings should be printed for deprecated items.
          */
diff --git a/src/main/java/org/bukkit/command/BlockCommandSender.java b/src/main/java/org/bukkit/command/BlockCommandSender.java
index 6dc46607..ce229d24 100644
--- a/src/main/java/org/bukkit/command/BlockCommandSender.java
+++ b/src/main/java/org/bukkit/command/BlockCommandSender.java
@@ -3,6 +3,7 @@ package org.bukkit.command;
 import org.bukkit.block.Block;
 
 public interface BlockCommandSender extends CommandSender {
+
     /**
      * Returns the block this command sender belongs to
      *
diff --git a/src/main/java/org/bukkit/command/MultipleCommandAlias.java b/src/main/java/org/bukkit/command/MultipleCommandAlias.java
index 3a666d16..a0a41295 100644
--- a/src/main/java/org/bukkit/command/MultipleCommandAlias.java
+++ b/src/main/java/org/bukkit/command/MultipleCommandAlias.java
@@ -11,6 +11,11 @@ public class MultipleCommandAlias extends Command {
         this.commands = commands;
     }
 
+    /**
+     * Gets the commands associated with the multi-command alias.
+     *
+     * @return commands associated with alias
+     */
     public Command[] getCommands() {
         return commands;
     }
diff --git a/src/main/java/org/bukkit/command/PluginCommand.java b/src/main/java/org/bukkit/command/PluginCommand.java
index ec66c28a..f90ee7e0 100644
--- a/src/main/java/org/bukkit/command/PluginCommand.java
+++ b/src/main/java/org/bukkit/command/PluginCommand.java
@@ -75,6 +75,7 @@ public final class PluginCommand extends Command implements PluginIdentifiableCo
 
     /**
      * Sets the {@link TabCompleter} to run when tab-completing this command.
+     * <p>
      * If no TabCompleter is specified, and the command's executor implements
      * TabCompleter, then the executor will be used for tab completion.
      *
@@ -112,6 +113,7 @@ public final class PluginCommand extends Command implements PluginIdentifiableCo
      * {@link Command#tabComplete(CommandSender, String, String[])}.<br>
      * <br>
      * This method does not consider permissions.
+     *
      * @throws CommandException if the completer or executor throw an exception during the process of tab-completing.
      * @throws IllegalArgumentException if sender, alias, or args is null
      */
diff --git a/src/main/java/org/bukkit/command/TabCommandExecutor.java b/src/main/java/org/bukkit/command/TabCommandExecutor.java
index 95efbd40..bf6ddd4e 100644
--- a/src/main/java/org/bukkit/command/TabCommandExecutor.java
+++ b/src/main/java/org/bukkit/command/TabCommandExecutor.java
@@ -4,6 +4,7 @@ import java.util.List;
 
 /**
  * Represents a class which can handle command tab completion and commands
+ *
  * @deprecated Remains for plugins that would have implemented it even without functionality
  * @see TabExecutor
  */
diff --git a/src/main/java/org/bukkit/configuration/InvalidConfigurationException.java b/src/main/java/org/bukkit/configuration/InvalidConfigurationException.java
index c60ff56e..81432139 100644
--- a/src/main/java/org/bukkit/configuration/InvalidConfigurationException.java
+++ b/src/main/java/org/bukkit/configuration/InvalidConfigurationException.java
@@ -5,6 +5,7 @@ package org.bukkit.configuration;
  */
 @SuppressWarnings("serial")
 public class InvalidConfigurationException extends Exception {
+
     /**
      * Creates a new instance of InvalidConfigurationException without a message or cause.
      */
diff --git a/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerializable.java b/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerializable.java
index 7eb01549..7bf4b299 100644
--- a/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerializable.java
+++ b/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerializable.java
@@ -16,10 +16,12 @@ import java.util.Map;
  * </ul>
  * In addition to implementing this interface, you must register the class with
  * {@link ConfigurationSerialization#registerClass(Class)}.
+ *
  * @see DelegateDeserialization
  * @see SerializableAs
  */
 public interface ConfigurationSerializable {
+
     /**
      * Creates a Map representation of this class.
      * <p>
diff --git a/src/main/java/org/bukkit/configuration/serialization/SerializableAs.java b/src/main/java/org/bukkit/configuration/serialization/SerializableAs.java
index db69dfc8..4612ab3a 100644
--- a/src/main/java/org/bukkit/configuration/serialization/SerializableAs.java
+++ b/src/main/java/org/bukkit/configuration/serialization/SerializableAs.java
@@ -15,6 +15,7 @@ import java.lang.annotation.Target;
  * <p>
  * Using this annotation on any other class than a {@link ConfigurationSerializable} will
  * have no effect.
+ *
  * @see ConfigurationSerialization#registerClass(Class, String)
  */
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/src/main/java/org/bukkit/entity/AnimalTamer.java b/src/main/java/org/bukkit/entity/AnimalTamer.java
index 89a77148..a80d31aa 100644
--- a/src/main/java/org/bukkit/entity/AnimalTamer.java
+++ b/src/main/java/org/bukkit/entity/AnimalTamer.java
@@ -1,6 +1,7 @@
 package org.bukkit.entity;
 
 public interface AnimalTamer {
+
     /**
      * This is the name of the specified AnimalTamer.
      *
diff --git a/src/main/java/org/bukkit/entity/ComplexEntityPart.java b/src/main/java/org/bukkit/entity/ComplexEntityPart.java
index 5db43e0a..f4ab0bbd 100644
--- a/src/main/java/org/bukkit/entity/ComplexEntityPart.java
+++ b/src/main/java/org/bukkit/entity/ComplexEntityPart.java
@@ -4,6 +4,7 @@ package org.bukkit.entity;
  * Represents a single part of a {@link ComplexLivingEntity}
  */
 public interface ComplexEntityPart extends Entity {
+
     /**
      * Gets the parent {@link ComplexLivingEntity} of this part.
      *
diff --git a/src/main/java/org/bukkit/entity/EntityType.java b/src/main/java/org/bukkit/entity/EntityType.java
index 49cc01ba..de3050ad 100644
--- a/src/main/java/org/bukkit/entity/EntityType.java
+++ b/src/main/java/org/bukkit/entity/EntityType.java
@@ -14,10 +14,11 @@ import org.bukkit.Location;
 import org.bukkit.World;
 
 public enum EntityType {
+
     // These strings MUST match the strings in nms.EntityTypes and are case sensitive.
     /**
      * An item resting on the ground.
-     *
+     * <p>
      * Spawn with {@link World#dropItem(Location, ItemStack)}
      * or {@link World#dropItemNaturally(Location, ItemStack)}
      */
diff --git a/src/main/java/org/bukkit/entity/ExperienceOrb.java b/src/main/java/org/bukkit/entity/ExperienceOrb.java
index 40783b89..c286edfd 100644
--- a/src/main/java/org/bukkit/entity/ExperienceOrb.java
+++ b/src/main/java/org/bukkit/entity/ExperienceOrb.java
@@ -4,6 +4,7 @@ package org.bukkit.entity;
  * Represents an Experience Orb.
  */
 public interface ExperienceOrb extends Entity {
+
     /**
      * Gets how much experience is contained within this orb
      *
diff --git a/src/main/java/org/bukkit/entity/Explosive.java b/src/main/java/org/bukkit/entity/Explosive.java
index bc68190c..48650f6a 100644
--- a/src/main/java/org/bukkit/entity/Explosive.java
+++ b/src/main/java/org/bukkit/entity/Explosive.java
@@ -4,6 +4,7 @@ package org.bukkit.entity;
  * A representation of an explosive entity
  */
 public interface Explosive extends Entity {
+
     /**
      * Set the radius affected by this explosive's explosion
      *
diff --git a/src/main/java/org/bukkit/entity/Fireball.java b/src/main/java/org/bukkit/entity/Fireball.java
index 95c60f8b..88876a47 100644
--- a/src/main/java/org/bukkit/entity/Fireball.java
+++ b/src/main/java/org/bukkit/entity/Fireball.java
@@ -6,6 +6,7 @@ import org.bukkit.util.Vector;
  * Represents a Fireball.
  */
 public interface Fireball extends Projectile, Explosive {
+
     /**
      * Fireballs fly straight and do not take setVelocity(...) well.
      *
diff --git a/src/main/java/org/bukkit/entity/Firework.java b/src/main/java/org/bukkit/entity/Firework.java
index b6138192..cd03b2f3 100644
--- a/src/main/java/org/bukkit/entity/Firework.java
+++ b/src/main/java/org/bukkit/entity/Firework.java
@@ -3,6 +3,7 @@ package org.bukkit.entity;
 import org.bukkit.inventory.meta.FireworkMeta;
 
 public interface Firework extends Entity {
+
     /**
      * Get a copy of the fireworks meta
      *
diff --git a/src/main/java/org/bukkit/entity/Ocelot.java b/src/main/java/org/bukkit/entity/Ocelot.java
index a173778b..4016d3fa 100644
--- a/src/main/java/org/bukkit/entity/Ocelot.java
+++ b/src/main/java/org/bukkit/entity/Ocelot.java
@@ -5,6 +5,7 @@ package org.bukkit.entity;
  * A wild tameable cat
  */
 public interface Ocelot extends Animals, Tameable {
+
     /**
      * Gets the current type of this cat.
      *
diff --git a/src/main/java/org/bukkit/entity/Painting.java b/src/main/java/org/bukkit/entity/Painting.java
index 3326a9fe..ddfa89d3 100644
--- a/src/main/java/org/bukkit/entity/Painting.java
+++ b/src/main/java/org/bukkit/entity/Painting.java
@@ -7,6 +7,7 @@ import org.bukkit.event.painting.PaintingBreakEvent;
  * Represents a Painting.
  */
 public interface Painting extends Hanging {
+
     /**
      * Get the art on this painting
      *
diff --git a/src/main/java/org/bukkit/entity/PigZombie.java b/src/main/java/org/bukkit/entity/PigZombie.java
index f8b1fb73..65a3f8cd 100644
--- a/src/main/java/org/bukkit/entity/PigZombie.java
+++ b/src/main/java/org/bukkit/entity/PigZombie.java
@@ -4,6 +4,7 @@ package org.bukkit.entity;
  * Represents a Pig Zombie.
  */
 public interface PigZombie extends Zombie {
+
     /**
      * Get the pig zombie's current anger level.
      *
diff --git a/src/main/java/org/bukkit/entity/Skeleton.java b/src/main/java/org/bukkit/entity/Skeleton.java
index 0019911b..02b76c36 100644
--- a/src/main/java/org/bukkit/entity/Skeleton.java
+++ b/src/main/java/org/bukkit/entity/Skeleton.java
@@ -4,6 +4,7 @@ package org.bukkit.entity;
  * Represents a Skeleton.
  */
 public interface Skeleton extends Monster {
+
     /**
      * Gets the current type of this skeleton.
      *
diff --git a/src/main/java/org/bukkit/entity/TNTPrimed.java b/src/main/java/org/bukkit/entity/TNTPrimed.java
index 3b5952c8..295dcb9b 100644
--- a/src/main/java/org/bukkit/entity/TNTPrimed.java
+++ b/src/main/java/org/bukkit/entity/TNTPrimed.java
@@ -4,6 +4,7 @@ package org.bukkit.entity;
  * Represents a Primed TNT.
  */
 public interface TNTPrimed extends Explosive {
+
     /**
      * Set the number of ticks until the TNT blows up after being primed.
      *
diff --git a/src/main/java/org/bukkit/entity/Zombie.java b/src/main/java/org/bukkit/entity/Zombie.java
index 7f1ffd19..59b52fd3 100644
--- a/src/main/java/org/bukkit/entity/Zombie.java
+++ b/src/main/java/org/bukkit/entity/Zombie.java
@@ -4,6 +4,7 @@ package org.bukkit.entity;
  * Represents a Zombie.
  */
 public interface Zombie extends Monster {
+
     /**
      * Gets whether the zombie is a baby
      *
diff --git a/src/main/java/org/bukkit/event/Cancellable.java b/src/main/java/org/bukkit/event/Cancellable.java
index 3fc13fc8..799b0b0f 100644
--- a/src/main/java/org/bukkit/event/Cancellable.java
+++ b/src/main/java/org/bukkit/event/Cancellable.java
@@ -1,6 +1,7 @@
 package org.bukkit.event;
 
 public interface Cancellable {
+
     /**
      * Gets the cancellation state of this event. A cancelled event will not
      * be executed in the server, but will still pass to other plugins
diff --git a/src/main/java/org/bukkit/event/EventPriority.java b/src/main/java/org/bukkit/event/EventPriority.java
index d087dec9..eb1400e0 100644
--- a/src/main/java/org/bukkit/event/EventPriority.java
+++ b/src/main/java/org/bukkit/event/EventPriority.java
@@ -4,6 +4,7 @@ package org.bukkit.event;
  * Represents an event's priority in execution
  */
 public enum EventPriority {
+
     /**
      * Event call is of very low importance and should be ran first, to allow
      * other plugins to further customise the outcome
diff --git a/src/main/java/org/bukkit/event/HandlerList.java b/src/main/java/org/bukkit/event/HandlerList.java
index f6d9014e..4b97a71b 100644
--- a/src/main/java/org/bukkit/event/HandlerList.java
+++ b/src/main/java/org/bukkit/event/HandlerList.java
@@ -10,6 +10,7 @@ import java.util.Map.Entry;
  * A list of event handlers, stored per-event. Based on lahwran's fevents.
  */
 public class HandlerList {
+
     /**
      * Handler array. This field being an array is the key to this system's speed.
      */
diff --git a/src/main/java/org/bukkit/event/entity/EntityCombustByBlockEvent.java b/src/main/java/org/bukkit/event/entity/EntityCombustByBlockEvent.java
index 7eed8ad4..c84bda9e 100644
--- a/src/main/java/org/bukkit/event/entity/EntityCombustByBlockEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityCombustByBlockEvent.java
@@ -3,6 +3,9 @@ package org.bukkit.event.entity;
 import org.bukkit.block.Block;
 import org.bukkit.entity.Entity;
 
+/**
+ * Called when a block causes an entity to combust.
+ */
 public class EntityCombustByBlockEvent extends EntityCombustEvent {
     private final Block combuster;
 
diff --git a/src/main/java/org/bukkit/event/entity/EntityCombustByEntityEvent.java b/src/main/java/org/bukkit/event/entity/EntityCombustByEntityEvent.java
index 84ca5c20..639567bd 100644
--- a/src/main/java/org/bukkit/event/entity/EntityCombustByEntityEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityCombustByEntityEvent.java
@@ -2,6 +2,9 @@ package org.bukkit.event.entity;
 
 import org.bukkit.entity.Entity;
 
+/**
+ * Called when an entity causes another entity to combust.
+ */
 public class EntityCombustByEntityEvent extends EntityCombustEvent {
     private final Entity combuster;
 
diff --git a/src/main/java/org/bukkit/event/entity/EntityPortalEvent.java b/src/main/java/org/bukkit/event/entity/EntityPortalEvent.java
index 0b4e6a9b..835c0548 100644
--- a/src/main/java/org/bukkit/event/entity/EntityPortalEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityPortalEvent.java
@@ -6,9 +6,10 @@ import org.bukkit.entity.Entity;
 import org.bukkit.event.HandlerList;
 
 /**
- * Called when a non-player entity is about to teleport because it is in contact with a portal
+ * Called when a non-player entity is about to teleport because it is in
+ * contact with a portal.
  * <p>
- * For players see {@link org.bukkit.event.player.PlayerPortalEvent PlayerPortalEvent}
+ * For players see {@link org.bukkit.event.player.PlayerPortalEvent}
  */
 public class EntityPortalEvent extends EntityTeleportEvent {
     private static final HandlerList handlers = new HandlerList();
@@ -20,18 +21,52 @@ public class EntityPortalEvent extends EntityTeleportEvent {
         this.travelAgent = pta;
     }
 
+    /**
+     * Sets whether or not the Travel Agent will be used.
+     * <p>
+     * If this is set to true, the TravelAgent will try to find a Portal at
+     * the {@link #getTo()} Location, and will try to create one if there is
+     * none.
+     * <p>
+     * If this is set to false, the {@link #getEntity()} will only be
+     * teleported to the {@link #getTo()} Location.
+     *
+     * @param useTravelAgent whether to use the Travel Agent
+     */
     public void useTravelAgent(boolean useTravelAgent) {
         this.useTravelAgent = useTravelAgent;
     }
 
+    /**
+     * Gets whether or not the Travel Agent will be used.
+     * <p>
+     * If this is set to true, the TravelAgent will try to find a Portal at
+     * the {@link #getTo()} Location, and will try to create one if there is
+     * none.
+     * <p>
+     * If this is set to false, the {@link #getEntity()} will only be
+     * teleported to the {@link #getTo()} Location.
+     *
+     * @return whether to use the Travel Agent
+     */
     public boolean useTravelAgent() {
         return useTravelAgent;
     }
 
+    /**
+     * Gets the Travel Agent used (or not) in this event.
+     *
+     * @return the Travel Agent used (or not) in this event
+     */
     public TravelAgent getPortalTravelAgent() {
         return this.travelAgent;
     }
 
+    /**
+     * Sets the Travel Agent used (or not) in this event.
+     *
+     * @param travelAgent the Travel Agent used (or not) in this event
+     */
     public void setPortalTravelAgent(TravelAgent travelAgent) {
         this.travelAgent = travelAgent;
     }
diff --git a/src/main/java/org/bukkit/event/entity/ItemDespawnEvent.java b/src/main/java/org/bukkit/event/entity/ItemDespawnEvent.java
index 6f4533c0..356e4bd9 100644
--- a/src/main/java/org/bukkit/event/entity/ItemDespawnEvent.java
+++ b/src/main/java/org/bukkit/event/entity/ItemDespawnEvent.java
@@ -5,6 +5,13 @@ import org.bukkit.entity.Item;
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 
+/**
+ * This event is called when a {@link org.bukkit.entity.Item} is removed from
+ * the world because it has existed for 5 minutes.
+ * <p>
+ * Cancelling the event results in the item being allowed to exist for 5 more
+ * minutes. This behavior is not guaranteed and may change in future versions.
+ */
 public class ItemDespawnEvent extends EntityEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
     private boolean canceled;
diff --git a/src/main/java/org/bukkit/event/inventory/ClickType.java b/src/main/java/org/bukkit/event/inventory/ClickType.java
index dc2928cc..c9e447fa 100644
--- a/src/main/java/org/bukkit/event/inventory/ClickType.java
+++ b/src/main/java/org/bukkit/event/inventory/ClickType.java
@@ -4,6 +4,7 @@ package org.bukkit.event.inventory;
  * What the client did to trigger this action (not the result).
  */
 public enum ClickType {
+
     /**
      * The left (or primary) mouse button.
      */
diff --git a/src/main/java/org/bukkit/event/inventory/CraftItemEvent.java b/src/main/java/org/bukkit/event/inventory/CraftItemEvent.java
index 4ebc36bd..ba3f5e5f 100644
--- a/src/main/java/org/bukkit/event/inventory/CraftItemEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/CraftItemEvent.java
@@ -5,6 +5,9 @@ import org.bukkit.inventory.CraftingInventory;
 import org.bukkit.inventory.InventoryView;
 import org.bukkit.inventory.Recipe;
 
+/**
+ * Called when the recipe of an Item is completed inside a crafting matrix.
+ */
 public class CraftItemEvent extends InventoryClickEvent {
     private Recipe recipe;
 
diff --git a/src/main/java/org/bukkit/event/inventory/InventoryAction.java b/src/main/java/org/bukkit/event/inventory/InventoryAction.java
index c9da0222..dbdbe26c 100644
--- a/src/main/java/org/bukkit/event/inventory/InventoryAction.java
+++ b/src/main/java/org/bukkit/event/inventory/InventoryAction.java
@@ -4,8 +4,10 @@ package org.bukkit.event.inventory;
  * An estimation of what the result will be.
  */
 public enum InventoryAction {
+
     /**
      * Nothing will happen from the click.
+     * <p>
      * There may be cases where nothing will happen and this is value is
      * not provided, but it is guaranteed that this value is accurate
      * when given.
diff --git a/src/main/java/org/bukkit/event/inventory/InventoryType.java b/src/main/java/org/bukkit/event/inventory/InventoryType.java
index 87edc427..06cabcd5 100644
--- a/src/main/java/org/bukkit/event/inventory/InventoryType.java
+++ b/src/main/java/org/bukkit/event/inventory/InventoryType.java
@@ -1,6 +1,7 @@
 package org.bukkit.event.inventory;
 
 public enum InventoryType {
+
     /**
      * A chest inventory, with 0, 9, 18, 27, 36, 45, or 54 slots of type CONTAINER.
      */
diff --git a/src/main/java/org/bukkit/event/player/PlayerBucketEvent.java b/src/main/java/org/bukkit/event/player/PlayerBucketEvent.java
index e1726a2d..d32c55e4 100644
--- a/src/main/java/org/bukkit/event/player/PlayerBucketEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerBucketEvent.java
@@ -7,6 +7,9 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
 import org.bukkit.inventory.ItemStack;
 
+/**
+ * Called when a player interacts with a Bucket
+ */
 public abstract class PlayerBucketEvent extends PlayerEvent implements Cancellable {
     private ItemStack itemStack;
     private boolean cancelled = false;
diff --git a/src/main/java/org/bukkit/event/player/PlayerEditBookEvent.java b/src/main/java/org/bukkit/event/player/PlayerEditBookEvent.java
index ed333930..da411d99 100644
--- a/src/main/java/org/bukkit/event/player/PlayerEditBookEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerEditBookEvent.java
@@ -77,7 +77,7 @@ public class PlayerEditBookEvent extends PlayerEvent implements Cancellable {
     /**
      * Sets the book meta that will actually be added to the book.
      *
-     * @param bookMeta new book meta
+     * @param newBookMeta new book meta
      * @throws IllegalArgumentException if the new book meta is null
      */
     public void setNewBookMeta(BookMeta newBookMeta) throws IllegalArgumentException {
diff --git a/src/main/java/org/bukkit/event/player/PlayerPortalEvent.java b/src/main/java/org/bukkit/event/player/PlayerPortalEvent.java
index 4706811f..93752f79 100644
--- a/src/main/java/org/bukkit/event/player/PlayerPortalEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerPortalEvent.java
@@ -6,7 +6,10 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.HandlerList;
 
 /**
- * Called when a player is about to teleport because it is in contact with a portal
+ * Called when a player is about to teleport because it is in contact with a
+ * portal.
+ * <p>
+ * For other entities see {@link org.bukkit.event.entity.EntityPortalEvent}
  */
 public class PlayerPortalEvent extends PlayerTeleportEvent {
     private static final HandlerList handlers = new HandlerList();
@@ -23,18 +26,52 @@ public class PlayerPortalEvent extends PlayerTeleportEvent {
         this.travelAgent = pta;
     }
 
+    /**
+     * Sets whether or not the Travel Agent will be used.
+     * <p>
+     * If this is set to true, the TravelAgent will try to find a Portal at
+     * the {@link #getTo()} Location, and will try to create one if there is
+     * none.
+     * <p>
+     * If this is set to false, the {@link #getPlayer()} will only be
+     * teleported to the {@link #getTo()} Location.
+     *
+     * @param useTravelAgent whether to use the Travel Agent
+     */
     public void useTravelAgent(boolean useTravelAgent) {
         this.useTravelAgent = useTravelAgent;
     }
 
+    /**
+     * Gets whether or not the Travel Agent will be used.
+     * <p>
+     * If this is set to true, the TravelAgent will try to find a Portal at
+     * the {@link #getTo()} Location, and will try to create one if there is
+     * none.
+     * <p>
+     * If this is set to false, the {@link #getPlayer()}} will only be
+     * teleported to the {@link #getTo()} Location.
+     *
+     * @return whether to use the Travel Agent
+     */
     public boolean useTravelAgent() {
         return useTravelAgent && travelAgent != null;
     }
 
+    /**
+     * Gets the Travel Agent used (or not) in this event.
+     *
+     * @return the Travel Agent used (or not) in this event
+     */
     public TravelAgent getPortalTravelAgent() {
         return this.travelAgent;
     }
 
+    /**
+     * Sets the Travel Agent used (or not) in this event.
+     *
+     * @param travelAgent the Travel Agent used (or not) in this event
+     */
     public void setPortalTravelAgent(TravelAgent travelAgent) {
         this.travelAgent = travelAgent;
     }
diff --git a/src/main/java/org/bukkit/event/vehicle/VehicleUpdateEvent.java b/src/main/java/org/bukkit/event/vehicle/VehicleUpdateEvent.java
index d84faf45..eebfdb15 100644
--- a/src/main/java/org/bukkit/event/vehicle/VehicleUpdateEvent.java
+++ b/src/main/java/org/bukkit/event/vehicle/VehicleUpdateEvent.java
@@ -3,6 +3,9 @@ package org.bukkit.event.vehicle;
 import org.bukkit.entity.Vehicle;
 import org.bukkit.event.HandlerList;
 
+/**
+ * Called when a vehicle updates
+ */
 public class VehicleUpdateEvent extends VehicleEvent {
     private static final HandlerList handlers = new HandlerList();
 
diff --git a/src/main/java/org/bukkit/generator/BlockPopulator.java b/src/main/java/org/bukkit/generator/BlockPopulator.java
index 041dc4fc..eacc8294 100644
--- a/src/main/java/org/bukkit/generator/BlockPopulator.java
+++ b/src/main/java/org/bukkit/generator/BlockPopulator.java
@@ -9,6 +9,7 @@ import org.bukkit.World;
  * For example, generating glowstone inside the nether or generating dungeons full of treasure
  */
 public abstract class BlockPopulator {
+
     /**
      * Populates an area of blocks at or around the given chunk.
      * <p>
diff --git a/src/main/java/org/bukkit/generator/ChunkGenerator.java b/src/main/java/org/bukkit/generator/ChunkGenerator.java
index 24e6aae3..875f276b 100644
--- a/src/main/java/org/bukkit/generator/ChunkGenerator.java
+++ b/src/main/java/org/bukkit/generator/ChunkGenerator.java
@@ -14,6 +14,7 @@ import org.bukkit.block.Block;
  * For example, the nether chunk generator should shape netherrack and soulsand
  */
 public abstract class ChunkGenerator {
+
     /**
      * Interface to biome data for chunk to be generated: initialized with default values for world type and seed.
      * <p>
diff --git a/src/main/java/org/bukkit/inventory/BeaconInventory.java b/src/main/java/org/bukkit/inventory/BeaconInventory.java
index deaf183d..d791f604 100644
--- a/src/main/java/org/bukkit/inventory/BeaconInventory.java
+++ b/src/main/java/org/bukkit/inventory/BeaconInventory.java
@@ -1,6 +1,7 @@
 package org.bukkit.inventory;
 
 public interface BeaconInventory extends Inventory {
+
     /**
      * Set the item powering the beacon.
      *
diff --git a/src/main/java/org/bukkit/inventory/BrewerInventory.java b/src/main/java/org/bukkit/inventory/BrewerInventory.java
index 735e86d8..91cd276b 100644
--- a/src/main/java/org/bukkit/inventory/BrewerInventory.java
+++ b/src/main/java/org/bukkit/inventory/BrewerInventory.java
@@ -3,6 +3,7 @@ package org.bukkit.inventory;
 import org.bukkit.block.BrewingStand;
 
 public interface BrewerInventory extends Inventory {
+
     /**
      * Get the current ingredient for brewing.
      *
diff --git a/src/main/java/org/bukkit/inventory/CraftingInventory.java b/src/main/java/org/bukkit/inventory/CraftingInventory.java
index 4b6cce44..e3b31b5e 100644
--- a/src/main/java/org/bukkit/inventory/CraftingInventory.java
+++ b/src/main/java/org/bukkit/inventory/CraftingInventory.java
@@ -4,6 +4,7 @@ package org.bukkit.inventory;
  * Interface to the crafting inventories
  */
 public interface CraftingInventory extends Inventory {
+
     /**
      * Check what item is in the result slot of this crafting inventory.
      *
diff --git a/src/main/java/org/bukkit/inventory/DoubleChestInventory.java b/src/main/java/org/bukkit/inventory/DoubleChestInventory.java
index 1a203205..0e419ed2 100644
--- a/src/main/java/org/bukkit/inventory/DoubleChestInventory.java
+++ b/src/main/java/org/bukkit/inventory/DoubleChestInventory.java
@@ -3,6 +3,7 @@ package org.bukkit.inventory;
 import org.bukkit.block.DoubleChest;
 
 public interface DoubleChestInventory extends Inventory {
+
     /**
      * Get the left half of this double chest.
      *
diff --git a/src/main/java/org/bukkit/inventory/EnchantingInventory.java b/src/main/java/org/bukkit/inventory/EnchantingInventory.java
index f1587330..9be1ee7f 100644
--- a/src/main/java/org/bukkit/inventory/EnchantingInventory.java
+++ b/src/main/java/org/bukkit/inventory/EnchantingInventory.java
@@ -1,6 +1,7 @@
 package org.bukkit.inventory;
 
 public interface EnchantingInventory extends Inventory {
+
     /**
      * Set the item being enchanted.
      *
diff --git a/src/main/java/org/bukkit/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java
index 01c35287..de682a66 100644
--- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
+++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
@@ -6,6 +6,7 @@ import org.bukkit.entity.Entity;
  * An interface to a creatures inventory
  */
 public interface EntityEquipment {
+
     /**
      * Gets a copy of the item the entity is currently holding
      *
diff --git a/src/main/java/org/bukkit/inventory/FurnaceInventory.java b/src/main/java/org/bukkit/inventory/FurnaceInventory.java
index f2219a65..5920083a 100644
--- a/src/main/java/org/bukkit/inventory/FurnaceInventory.java
+++ b/src/main/java/org/bukkit/inventory/FurnaceInventory.java
@@ -3,6 +3,7 @@ package org.bukkit.inventory;
 import org.bukkit.block.Furnace;
 
 public interface FurnaceInventory extends Inventory {
+
     /**
      * Get the current item in the result slot.
      *
diff --git a/src/main/java/org/bukkit/inventory/Inventory.java b/src/main/java/org/bukkit/inventory/Inventory.java
index aa4373f1..436e7e49 100644
--- a/src/main/java/org/bukkit/inventory/Inventory.java
+++ b/src/main/java/org/bukkit/inventory/Inventory.java
@@ -171,21 +171,28 @@ public interface Inventory extends Iterable<ItemStack> {
     public boolean contains(Material material, int amount) throws IllegalArgumentException;
 
     /**
-     * Checks if the inventory contains any ItemStacks matching the given ItemStack and at least the minimum amount specified
-     * This will only match if both the type and the amount of the stack match
+     * Checks if the inventory contains at least the minimum amount specified
+     * of exactly matching ItemStacks.
+     * <p>
+     * An ItemStack only counts if both the type and the amount of the stack
+     * match.
      *
-     * @param item The ItemStack to match against
-     * @param amount The amount of stacks to find
-     * @return false if item is null, true if amount less than 1, true if amount of exactly matching ItemStacks were found.
+     * @param item the ItemStack to match against
+     * @param amount how many identical stacks to check for
+     * @return false if item is null, true if amount less than 1, true if
+     *     amount of exactly matching ItemStacks were found
+     * @see #containsAtLeast(ItemStack, int)
      */
     public boolean contains(ItemStack item, int amount);
 
     /**
-     * Checks if the inventory contains any ItemStacks matching the given ItemStack and at least the minimum amount specified
+     * Checks if the inventory contains ItemStacks matching the given
+     * ItemStack whose amounts sum to at least the minimum amount specified.
      *
-     * @param item The ItemStack to match against
-     * @param amount The minimum amount
-     * @return false if item is null, true if amount less than 1, true if enough ItemStacks were found to add to the given amount
+     * @param item the ItemStack to match against
+     * @param amount the minimum amount
+     * @return false if item is null, true if amount less than 1, true if
+     *     enough ItemStacks were found to add to the given amount
      */
     public boolean containsAtLeast(ItemStack item, int amount);
 
diff --git a/src/main/java/org/bukkit/inventory/InventoryHolder.java b/src/main/java/org/bukkit/inventory/InventoryHolder.java
index 9d788438..9c06a3d7 100644
--- a/src/main/java/org/bukkit/inventory/InventoryHolder.java
+++ b/src/main/java/org/bukkit/inventory/InventoryHolder.java
@@ -1,6 +1,7 @@
 package org.bukkit.inventory;
 
 public interface InventoryHolder {
+
     /**
      * Get the object's inventory.
      *
diff --git a/src/main/java/org/bukkit/permissions/Permissible.java b/src/main/java/org/bukkit/permissions/Permissible.java
index e094f069..66a0c810 100644
--- a/src/main/java/org/bukkit/permissions/Permissible.java
+++ b/src/main/java/org/bukkit/permissions/Permissible.java
@@ -7,6 +7,7 @@ import org.bukkit.plugin.Plugin;
  * Represents an object that may be assigned permissions
  */
 public interface Permissible extends ServerOperator {
+
     /**
      * Checks if this object contains an override for the specified permission, by fully qualified name
      *
diff --git a/src/main/java/org/bukkit/permissions/PermissionRemovedExecutor.java b/src/main/java/org/bukkit/permissions/PermissionRemovedExecutor.java
index a9543cf8..aa797eec 100644
--- a/src/main/java/org/bukkit/permissions/PermissionRemovedExecutor.java
+++ b/src/main/java/org/bukkit/permissions/PermissionRemovedExecutor.java
@@ -4,6 +4,7 @@ package org.bukkit.permissions;
  * Represents a class which is to be notified when a {@link PermissionAttachment} is removed from a {@link Permissible}
  */
 public interface PermissionRemovedExecutor {
+
     /**
      * Called when a {@link PermissionAttachment} is removed from a {@link Permissible}
      *
diff --git a/src/main/java/org/bukkit/permissions/ServerOperator.java b/src/main/java/org/bukkit/permissions/ServerOperator.java
index 721c42a3..e4faa87f 100644
--- a/src/main/java/org/bukkit/permissions/ServerOperator.java
+++ b/src/main/java/org/bukkit/permissions/ServerOperator.java
@@ -6,6 +6,7 @@ import org.bukkit.entity.Player;
  * Represents an object that may become a server operator, such as a {@link Player}
  */
 public interface ServerOperator {
+
     /**
      * Checks if this object is a server operator
      *
diff --git a/src/main/java/org/bukkit/potion/Potion.java b/src/main/java/org/bukkit/potion/Potion.java
index 800a375b..43e5694c 100644
--- a/src/main/java/org/bukkit/potion/Potion.java
+++ b/src/main/java/org/bukkit/potion/Potion.java
@@ -37,7 +37,9 @@ public class Potion {
         }
     }
 
-    /** @deprecated In favour of {@link #Potion(PotionType, int)} */
+    /**
+     * @deprecated In favour of {@link #Potion(PotionType, int)}
+     */
     @SuppressWarnings("javadoc")
     @Deprecated
     public Potion(PotionType type, Tier tier) {
@@ -45,14 +47,18 @@ public class Potion {
         Validate.notNull(type, "Type cannot be null");
     }
 
-    /** @deprecated In favour of {@link #Potion(PotionType, int, boolean)} */
+    /**
+     * @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)} */
+    /**
+     * @deprecated In favour of {@link #Potion(PotionType, int, boolean, boolean)}
+     */
     @SuppressWarnings("javadoc")
     @Deprecated
     public Potion(PotionType type, Tier tier, boolean splash, boolean extended) {
diff --git a/src/main/java/org/bukkit/potion/PotionBrewer.java b/src/main/java/org/bukkit/potion/PotionBrewer.java
index d85a1d63..ba5f20c9 100644
--- a/src/main/java/org/bukkit/potion/PotionBrewer.java
+++ b/src/main/java/org/bukkit/potion/PotionBrewer.java
@@ -6,6 +6,7 @@ import java.util.Collection;
  * Represents a brewer that can create {@link PotionEffect}s.
  */
 public interface PotionBrewer {
+
     /**
      * Creates a {@link PotionEffect} from the given {@link PotionEffectType},
      * applying duration modifiers and checks.
diff --git a/src/main/java/org/bukkit/scheduler/BukkitTask.java b/src/main/java/org/bukkit/scheduler/BukkitTask.java
index 890c7315..e447e64e 100644
--- a/src/main/java/org/bukkit/scheduler/BukkitTask.java
+++ b/src/main/java/org/bukkit/scheduler/BukkitTask.java
@@ -5,7 +5,6 @@ import org.bukkit.plugin.Plugin;
 /**
  * Represents a task being executed by the scheduler
  */
-
 public interface BukkitTask {
 
     /**
diff --git a/src/main/java/org/bukkit/scheduler/BukkitWorker.java b/src/main/java/org/bukkit/scheduler/BukkitWorker.java
index a889e893..4df43a6a 100644
--- a/src/main/java/org/bukkit/scheduler/BukkitWorker.java
+++ b/src/main/java/org/bukkit/scheduler/BukkitWorker.java
@@ -8,7 +8,6 @@ import org.bukkit.plugin.Plugin;
  * </p>
  * Workers are used to execute async tasks.
  */
-
 public interface BukkitWorker {
 
     /**
diff --git a/src/main/java/org/bukkit/util/FileUtil.java b/src/main/java/org/bukkit/util/FileUtil.java
index 2e137675..7cabf4c5 100644
--- a/src/main/java/org/bukkit/util/FileUtil.java
+++ b/src/main/java/org/bukkit/util/FileUtil.java
@@ -9,7 +9,6 @@ import java.io.IOException;
 /**
  * Class containing file utilities
  */
-
 public class FileUtil {
 
     /**
@@ -19,7 +18,6 @@ public class FileUtil {
      * @param outFile the target filename
      * @return true on success
      */
-
     public static boolean copy(File inFile, File outFile) {
         if (!inFile.exists()) {
             return false;
diff --git a/src/main/java/org/bukkit/util/io/BukkitObjectInputStream.java b/src/main/java/org/bukkit/util/io/BukkitObjectInputStream.java
index ed5675fe..d4b28251 100644
--- a/src/main/java/org/bukkit/util/io/BukkitObjectInputStream.java
+++ b/src/main/java/org/bukkit/util/io/BukkitObjectInputStream.java
@@ -23,7 +23,7 @@ public class BukkitObjectInputStream extends ObjectInputStream {
      *
      * @throws IOException
      * @throws SecurityException
-     * @see {@link ObjectInputStream#ObjectInputStream()}
+     * @see ObjectInputStream#ObjectInputStream()
      */
     protected BukkitObjectInputStream() throws IOException, SecurityException {
         super();
@@ -35,7 +35,7 @@ public class BukkitObjectInputStream extends ObjectInputStream {
      *
      * @param in
      * @throws IOException
-     * @see {@link ObjectInputStream#ObjectInputStream(InputStream)}
+     * @see ObjectInputStream#ObjectInputStream(InputStream)
      */
     public BukkitObjectInputStream(InputStream in) throws IOException {
         super(in);
diff --git a/src/main/java/org/bukkit/util/io/BukkitObjectOutputStream.java b/src/main/java/org/bukkit/util/io/BukkitObjectOutputStream.java
index afdd7e3f..c11e2029 100644
--- a/src/main/java/org/bukkit/util/io/BukkitObjectOutputStream.java
+++ b/src/main/java/org/bukkit/util/io/BukkitObjectOutputStream.java
@@ -23,7 +23,7 @@ public class BukkitObjectOutputStream extends ObjectOutputStream {
      *
      * @throws IOException
      * @throws SecurityException
-     * @see {@link ObjectOutputStream#ObjectOutputStream()}
+     * @see ObjectOutputStream#ObjectOutputStream()
      */
     protected BukkitObjectOutputStream() throws IOException, SecurityException {
         super();
@@ -35,7 +35,7 @@ public class BukkitObjectOutputStream extends ObjectOutputStream {
      *
      * @param out
      * @throws IOException
-     * @see {@link ObjectOutputStream#ObjectOutputStream(OutputStream)}
+     * @see ObjectOutputStream#ObjectOutputStream(OutputStream)
      */
     public BukkitObjectOutputStream(OutputStream out) throws IOException {
         super(out);