Pulling all pending Bukkit-JavaDoc changes

10 files changed, 85 insertions, 16 deletions

diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
index 62fadda7..63507c9f 100644
--- a/src/main/java/org/bukkit/World.java
+++ b/src/main/java/org/bukkit/World.java
@@ -291,12 +291,12 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * Creates an {@link Arrow} entity at the given {@link Location}
      *
      * @param location Location to spawn the arrow
-     * @param velocity Velocity to shoot the arrow in
+     * @param direction Direction to shoot the arrow in
      * @param speed Speed of the arrow. A recommend speed is 0.6
      * @param spread Spread of the arrow. A recommend spread is 12
      * @return Arrow entity spawned as a result of this method
      */
-    public Arrow spawnArrow(Location location, Vector velocity, float speed, float spread);
+    public Arrow spawnArrow(Location location, Vector direction, float speed, float spread);
 
     /**
      * Creates a tree at the given {@link Location}
diff --git a/src/main/java/org/bukkit/command/Command.java b/src/main/java/org/bukkit/command/Command.java
index 073f1acf..4ad60996 100644
--- a/src/main/java/org/bukkit/command/Command.java
+++ b/src/main/java/org/bukkit/command/Command.java
@@ -172,7 +172,7 @@ public abstract class Command {
     }
 
     /**
-     * Returns the current lable for this command
+     * Returns the current label for this command
      *
      * @return Label of this command or null if not registered
      */
diff --git a/src/main/java/org/bukkit/conversations/ConversationFactory.java b/src/main/java/org/bukkit/conversations/ConversationFactory.java
index d5214a56..59104d74 100644
--- a/src/main/java/org/bukkit/conversations/ConversationFactory.java
+++ b/src/main/java/org/bukkit/conversations/ConversationFactory.java
@@ -133,9 +133,9 @@ public class ConversationFactory {
 
 
     /**
-     * Adds a {@link ConversationCanceller to constructed conversations.}
+     * Adds a {@link ConversationCanceller} to constructed conversations.
      *
-     * @param canceller The {@link ConversationCanceller to add.}
+     * @param canceller The {@link ConversationCanceller} to add.
      * @return This object.
      */
     public ConversationFactory withConversationCanceller(ConversationCanceller canceller) {
diff --git a/src/main/java/org/bukkit/event/block/Action.java b/src/main/java/org/bukkit/event/block/Action.java
index b8d2bcb7..0fc3af1a 100644
--- a/src/main/java/org/bukkit/event/block/Action.java
+++ b/src/main/java/org/bukkit/event/block/Action.java
@@ -19,7 +19,7 @@ public enum Action {
      */
     RIGHT_CLICK_AIR,
     /**
-     * Ass-pressure
+     * Stepping onto or into a block (Ass-pressure)
      */
     PHYSICAL,
 }
diff --git a/src/main/java/org/bukkit/event/block/BlockBreakEvent.java b/src/main/java/org/bukkit/event/block/BlockBreakEvent.java
index 0cf1d39a..de9a2b49 100644
--- a/src/main/java/org/bukkit/event/block/BlockBreakEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockBreakEvent.java
@@ -14,7 +14,7 @@ import org.bukkit.event.HandlerList;
  * <li />The player is not in creative or adventure mode
  * <li />The player can loot the block (ie: does not destroy it completely, by using the correct tool)
  * <li />The player does not have silk touch
- * <li />The block drops experience in vanilla MineCraft
+ * <li />The block drops experience in vanilla Minecraft
  * </ol>
  * <p>
  * Note:
diff --git a/src/main/java/org/bukkit/event/block/BlockFadeEvent.java b/src/main/java/org/bukkit/event/block/BlockFadeEvent.java
index a39e1dfa..7d0120cb 100644
--- a/src/main/java/org/bukkit/event/block/BlockFadeEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockFadeEvent.java
@@ -12,6 +12,7 @@ import org.bukkit.event.HandlerList;
  * <ul>
  * <li>Snow melting due to being near a light source.</li>
  * <li>Ice melting due to being near a light source.</li>
+ * <li>Fire burning out after time, without destroying fuel block.</li>
  * </ul>
  * <p>
  * If a Block Fade event is cancelled, the block will not fade, melt or disappear.
diff --git a/src/main/java/org/bukkit/event/block/SignChangeEvent.java b/src/main/java/org/bukkit/event/block/SignChangeEvent.java
index d1efb1a5..d1b7908d 100644
--- a/src/main/java/org/bukkit/event/block/SignChangeEvent.java
+++ b/src/main/java/org/bukkit/event/block/SignChangeEvent.java
@@ -25,7 +25,7 @@ public class SignChangeEvent extends BlockEvent implements Cancellable {
     /**
      * Gets the player changing the sign involved in this event.
      *
-     * @return The Player involved in this event.
+     * @return the Player involved in this event
      */
     public Player getPlayer() {
         return player;
@@ -34,7 +34,7 @@ public class SignChangeEvent extends BlockEvent implements Cancellable {
     /**
      * Gets all of the lines of text from the sign involved in this event.
      *
-     * @return A String[] of the sign's lines of text
+     * @return the String array for the sign's lines new text
      */
     public String[] getLines() {
         return lines;
@@ -44,8 +44,10 @@ public class SignChangeEvent extends BlockEvent implements Cancellable {
      * Gets a single line of text from the sign involved in this event.
      *
      * @param index index of the line to get
-     * @return The String containing the line of text associated with the provided index
-     * @throws IndexOutOfBoundsException thrown when the provided index is > 4 and < 0
+     * @return the String containing the line of text associated with the
+     *     provided index
+     * @throws IndexOutOfBoundsException thrown when the provided index is > 3
+     *     or < 0
      */
     public String getLine(int index) throws IndexOutOfBoundsException {
         return lines[index];
@@ -56,7 +58,8 @@ public class SignChangeEvent extends BlockEvent implements Cancellable {
      *
      * @param index index of the line to set
      * @param line text to set
-     * @throws IndexOutOfBoundsException thrown when the provided index is > 4 and < 0
+     * @throws IndexOutOfBoundsException thrown when the provided index is > 3
+     *     or < 0
      */
     public void setLine(int index, String line) throws IndexOutOfBoundsException {
         lines[index] = line;
diff --git a/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java b/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java
index dbcaa233..5fbdc145 100644
--- a/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java
@@ -10,8 +10,41 @@ import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 
 /**
- * Called early in the command handling process. This event is only
- * for very exceptional cases and you should not normally use it.
+ * This event is called whenever a player runs a command (by placing a slash
+ * at the start of their message). It is called early in the command handling
+ * process, and modifications in this event (via {@link #setMessage(String)})
+ * will be shown in the behavior.
+ * <p>
+ * Many plugins will have <b>no use for this event</b>, and you should
+ * attempt to avoid using it if it is not necessary.
+ * <p>
+ * Some examples of valid uses for this event are:
+ * <ul>
+ * <li>Logging executed commands to a separate file
+ * <li>Variable substitution. For example, replacing
+ *     <code>${nearbyPlayer}</code> with the name of the nearest other
+ *     player, or simulating the <code>@a</code> and <code>@p</code>
+ *     decorators used by Command Blocks in plugins that do not handle it.
+ * <li>Conditionally blocking commands belonging to other plugins. For
+ *     example, blocking the use of the <code>/home</code> command in a
+ *     combat arena.
+ * <li>Per-sender command aliases. For example, after a player runs the
+ *     command <code>/calias cr gamemode creative</code>, the next time they
+ *     run <code>/cr</code>, it gets replaced into
+ *     <code>/gamemode creative</code>. (Global command aliases should be
+ *     done by registering the alias.)
+ * </ul>
+ * <p>
+ * Examples of incorrect uses are:
+ * <ul>
+ * <li>Using this event to run command logic
+ * </ul>
+ * <p>
+ * If the event is cancelled, processing of the command will halt.
+ * <p>
+ * The state of whether or not there is a slash (<code>/</code>) at the
+ * beginning of the message should be preserved. If a slash is added or
+ * removed, unexpected behavior may result.
  */
 public class PlayerCommandPreprocessEvent extends PlayerEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/org/bukkit/event/server/RemoteServerCommandEvent.java b/src/main/java/org/bukkit/event/server/RemoteServerCommandEvent.java
index d987a455..2a49237c 100644
--- a/src/main/java/org/bukkit/event/server/RemoteServerCommandEvent.java
+++ b/src/main/java/org/bukkit/event/server/RemoteServerCommandEvent.java
@@ -4,7 +4,8 @@ import org.bukkit.command.CommandSender;
 import org.bukkit.event.HandlerList;
 
 /**
- * Remote Server Command events
+ * This event is called when a command is recieved over RCON. See the javadocs
+ * of {@link ServerCommandEvent} for more information.
  */
 public class RemoteServerCommandEvent extends ServerCommandEvent {
     private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/org/bukkit/event/server/ServerCommandEvent.java b/src/main/java/org/bukkit/event/server/ServerCommandEvent.java
index 3e4d816d..edf4e2a4 100644
--- a/src/main/java/org/bukkit/event/server/ServerCommandEvent.java
+++ b/src/main/java/org/bukkit/event/server/ServerCommandEvent.java
@@ -4,7 +4,38 @@ import org.bukkit.command.CommandSender;
 import org.bukkit.event.HandlerList;
 
 /**
- * Server Command events
+ * This event is called when a command is run from the server console. It is
+ * called early in the command handling process, and modifications in this
+ * event (via {@link #setCommand(String)}) will be shown in the behavior.
+ * <p>
+ * Many plugins will have <b>no use for this event</b>, and you should
+ * attempt to avoid using it if it is not necessary.
+ * <p>
+ * Some examples of valid uses for this event are:
+ * <ul>
+ * <li>Logging executed commands to a separate file
+ * <li>Variable substitution. For example, replacing <code>${ip:Steve}</code>
+ *     with the connection IP of the player named Steve, or simulating the
+ *     <code>@a</code> and <code>@p</code> decorators used by Command Blocks
+ *     for plugins that do not handle it.
+ * <li>Conditionally blocking commands belonging to other plugins.
+ * <li>Per-sender command aliases. For example, after the console runs the
+ *     command <code>/calias cr gamemode creative</code>, the next time they
+ *     run <code>/cr</code>, it gets replaced into
+ *     <code>/gamemode creative</code>. (Global command aliases should be
+ *     done by registering the alias.)
+ * </ul>
+ * <p>
+ * Examples of incorrect uses are:
+ * <ul>
+ * <li>Using this event to run command logic
+ * </ul>
+ * <p>
+ * If the event is cancelled, processing of the command will halt.
+ * <p>
+ * The state of whether or not there is a slash (<code>/</code>) at the
+ * beginning of the message should be preserved. If a slash is added or
+ * removed, unexpected behavior may result.
  */
 public class ServerCommandEvent extends ServerEvent {
     private static final HandlerList handlers = new HandlerList();