Pulling all pending Bukkit-JavaDoc changes

A special thanks goes to @aerouk for almost all of the changes found here.

src/main/java/org/bukkit/Achievement.java

@@ -40,7 +40,8 @@ public enum Achievement {
     ;
 
     /**
-     * The offset used to distinguish Achievements and Statistics
+     * The offset used to distinguish Achievements and Statistics.
+     *
      * @deprecated Magic value
      */
     @Deprecated

src/main/java/org/bukkit/BlockChangeDelegate.java

@@ -8,8 +8,11 @@
 public interface BlockChangeDelegate {
 
     /**
-     * Set a block type at the specified coordinates without doing all world updates and notifications.
-     * It is safe to have this call World.setTypeId, but it may be slower than World.setRawTypeId.
+     * Set a block type at the specified coordinates without doing all world
+     * updates and notifications.
+     * <p>
+     * It is safe to have this call World.setTypeId, but it may be slower than
+     * World.setRawTypeId.
      *
      * @param x X coordinate
      * @param y Y coordinate
@@ -22,8 +25,11 @@ public interface BlockChangeDelegate {
     public boolean setRawTypeId(int x, int y, int z, int typeId);
 
     /**
-     * Set a block type and data at the specified coordinates without doing all world updates and notifications.
-     * It is safe to have this call World.setTypeId, but it may be slower than World.setRawTypeId.
+     * Set a block type and data at the specified coordinates without doing
+     * all world updates and notifications.
+     * <p>
+     * It is safe to have this call World.setTypeId, but it may be slower than
+     * World.setRawTypeId.
      *
      * @param x X coordinate
      * @param y Y coordinate
@@ -38,6 +44,7 @@ public interface BlockChangeDelegate {
 
     /**
      * Set a block type at the specified coordinates.
+     * <p>
      * This method cannot call World.setRawTypeId, a full update is needed.
      *
      * @param x X coordinate
@@ -52,6 +59,7 @@ public interface BlockChangeDelegate {
 
     /**
      * Set a block type and data at the specified coordinates.
+     * <p>
      * This method cannot call World.setRawTypeId, a full update is needed.
      *
      * @param x X coordinate

src/main/java/org/bukkit/Bukkit.java

@@ -574,7 +574,8 @@ public static Inventory createInventory(InventoryHolder owner, int size) {
     }
 
     /**
-     * @see Server#createInventory(InventoryHolder owner, int size, String title)
+     * @see Server#createInventory(InventoryHolder owner, int size, String
+     *     title)
      */
     public static Inventory createInventory(InventoryHolder owner, int size, String title) {
         return server.createInventory(owner, size, title);

src/main/java/org/bukkit/ChatColor.java

@@ -101,8 +101,8 @@ public enum ChatColor {
     RESET('r', 0x15);
 
     /**
-     * The special character which prefixes all chat colour codes. Use this if you need to dynamically
-     * convert colour codes from your custom format.
+     * The special character which prefixes all chat colour codes. Use this if
+     * you need to dynamically convert colour codes from your custom format.
      */
     public static final char COLOR_CHAR = '\u00A7';
     private static final Pattern STRIP_COLOR_PATTERN = Pattern.compile("(?i)" + String.valueOf(COLOR_CHAR) + "[0-9A-FK-OR]");
@@ -157,7 +157,8 @@ public boolean isColor() {
      * Gets the color represented by the specified color code
      *
      * @param code Code to check
-     * @return Associative {@link org.bukkit.ChatColor} with the given code, or null if it doesn't exist
+     * @return Associative {@link org.bukkit.ChatColor} with the given code,
+     *     or null if it doesn't exist
      */
     public static ChatColor getByChar(char code) {
         return BY_CHAR.get(code);
@@ -167,7 +168,8 @@ public static ChatColor getByChar(char code) {
      * Gets the color represented by the specified color code
      *
      * @param code Code to check
-     * @return Associative {@link org.bukkit.ChatColor} with the given code, or null if it doesn't exist
+     * @return Associative {@link org.bukkit.ChatColor} with the given code,
+     *     or null if it doesn't exist
      */
     public static ChatColor getByChar(String code) {
         Validate.notNull(code, "Code cannot be null");
@@ -191,9 +193,10 @@ public static String stripColor(final String input) {
     }
 
     /**
-     * Translates a string using an alternate color code character into a string that uses the internal
-     * ChatColor.COLOR_CODE color code character. The alternate color code character will only be replaced
-     * if it is immediately followed by 0-9, A-F, a-f, K-O, k-o, R or r.
+     * Translates a string using an alternate color code character into a
+     * string that uses the internal ChatColor.COLOR_CODE color code
+     * character. The alternate color code character will only be replaced if
+     * it is immediately followed by 0-9, A-F, a-f, K-O, k-o, R or r.
      *
      * @param altColorChar The alternate color code character to replace. Ex: &
      * @param textToTranslate Text containing the alternate color code character.

src/main/java/org/bukkit/Chunk.java

@@ -50,9 +50,12 @@ public interface Chunk {
     /**
      * Capture thread-safe read-only snapshot of chunk data
      *
-     * @param includeMaxblocky - if true, snapshot includes per-coordinate maximum Y values
-     * @param includeBiome - if true, snapshot includes per-coordinate biome type
-     * @param includeBiomeTempRain - if true, snapshot includes per-coordinate raw biome temperature and rainfall
+     * @param includeMaxblocky - if true, snapshot includes per-coordinate
+     *     maximum Y values
+     * @param includeBiome - if true, snapshot includes per-coordinate biome
+     *     type
+     * @param includeBiomeTempRain - if true, snapshot includes per-coordinate
+     *     raw biome temperature and rainfall
      * @return ChunkSnapshot
      */
     ChunkSnapshot getChunkSnapshot(boolean includeMaxblocky, boolean includeBiome, boolean includeBiomeTempRain);
@@ -81,7 +84,8 @@ public interface Chunk {
     /**
      * Loads the chunk.
      *
-     * @param generate Whether or not to generate a chunk if it doesn't already exist
+     * @param generate Whether or not to generate a chunk if it doesn't
+     *     already exist
      * @return true if the chunk has loaded successfully, otherwise false
      */
     boolean load(boolean generate);
@@ -97,7 +101,8 @@ public interface Chunk {
      * Unloads and optionally saves the Chunk
      *
      * @param save Controls whether the chunk is saved
-     * @param safe Controls whether to unload the chunk when players are nearby
+     * @param safe Controls whether to unload the chunk when players are
+     *     nearby
      * @return true if the chunk has unloaded successfully, otherwise false
      */
     boolean unload(boolean save, boolean safe);

src/main/java/org/bukkit/ChunkSnapshot.java

@@ -3,8 +3,10 @@
 import org.bukkit.block.Biome;
 
 /**
- * Represents a static, thread-safe snapshot of chunk of blocks
- * Purpose is to allow clean, efficient copy of a chunk data to be made, and then handed off for processing in another thread (e.g. map rendering)
+ * Represents a static, thread-safe snapshot of chunk of blocks.
+ * <p>
+ * Purpose is to allow clean, efficient copy of a chunk data to be made, and
+ * then handed off for processing in another thread (e.g. map rendering)
  */
 public interface ChunkSnapshot {
 
@@ -64,7 +66,8 @@ public interface ChunkSnapshot {
     int getBlockSkyLight(int x, int y, int z);
 
     /**
-     * Get light level emitted by block at corresponding coordinate in the chunk
+     * Get light level emitted by block at corresponding coordinate in the
+     * chunk
      *
      * @param x 0-15
      * @param y 0-127

src/main/java/org/bukkit/CoalType.java

@@ -32,10 +32,9 @@ public byte getData() {
     /**
      * Gets the type of coal with the given data value
      *
-     * @param data
-     *            Data value to fetch
+     * @param data Data value to fetch
      * @return The {@link CoalType} representing the given value, or null if
-     *         it doesn't exist
+     *     it doesn't exist
      * @deprecated Magic value
      */
     @Deprecated

src/main/java/org/bukkit/Color.java

@@ -9,8 +9,9 @@
 import com.google.common.collect.ImmutableMap;
 
 /**
- * A container for a color palette. This class is immutable; the set methods return a new color.
- * The color names listed as fields are HTML4 standards, but subject to change.
+ * A container for a color palette. This class is immutable; the set methods
+ * return a new color. The color names listed as fields are HTML4 standards,
+ * but subject to change.
  */
 @SerializableAs("Color")
 public final class Color implements ConfigurationSerializable {
@@ -132,23 +133,27 @@ public static Color fromBGR(int blue, int green, int red) throws IllegalArgument
     }
 
     /**
-     * Creates a new color object from an integer that contains the red, green, and blue bytes in the lowest order 24 bits.
+     * Creates a new color object from an integer that contains the red,
+     * green, and blue bytes in the lowest order 24 bits.
      *
      * @param rgb the integer storing the red, green, and blue values
      * @return a new color object for specified values
-     * @throws IllegalArgumentException if any data is in the highest order 8 bits
+     * @throws IllegalArgumentException if any data is in the highest order 8
+     *     bits
      */
     public static Color fromRGB(int rgb) throws IllegalArgumentException {
         Validate.isTrue((rgb >> 24) == 0, "Extrenuous data in: ", rgb);
         return fromRGB(rgb >> 16 & BIT_MASK, rgb >> 8 & BIT_MASK, rgb >> 0 & BIT_MASK);
     }
 
     /**
-     * Creates a new color object from an integer that contains the blue, green, and red bytes in the lowest order 24 bits.
+     * Creates a new color object from an integer that contains the blue,
+     * green, and red bytes in the lowest order 24 bits.
      *
      * @param bgr the integer storing the blue, green, and red values
      * @return a new color object for specified values
-     * @throws IllegalArgumentException if any data is in the highest order 8 bits
+     * @throws IllegalArgumentException if any data is in the highest order 8
+     *     bits
      */
     public static Color fromBGR(int bgr) throws IllegalArgumentException {
         Validate.isTrue((bgr >> 24) == 0, "Extrenuous data in: ", bgr);
@@ -239,8 +244,8 @@ public int asBGR() {
     }
 
     /**
-     * Creates a new color with its RGB components changed as if it was dyed with the colors passed in, replicating
-     * vanilla workbench dyeing
+     * Creates a new color with its RGB components changed as if it was dyed
+     * with the colors passed in, replicating vanilla workbench dyeing
      *
      * @param colors The DyeColors to dye with
      * @return A new color with the changed rgb components
@@ -258,8 +263,8 @@ public Color mixDyes(DyeColor... colors) {
     }
 
     /**
-     * Creates a new color with its RGB components changed as if it was dyed with the colors passed in, replicating
-     * vanilla workbench dyeing
+     * Creates a new color with its RGB components changed as if it was dyed
+     * with the colors passed in, replicating vanilla workbench dyeing
      *
      * @param colors The colors to dye with
      * @return A new color with the changed rgb components

src/main/java/org/bukkit/CropState.java

@@ -63,10 +63,9 @@ public byte getData() {
     /**
      * Gets the CropState with the given data value
      *
-     * @param data
-     *            Data value to fetch
+     * @param data Data value to fetch
      * @return The {@link CropState} representing the given value, or null if
-     *         it doesn't exist
+     *     it doesn't exist
      * @deprecated Magic value
      */
     @Deprecated

src/main/java/org/bukkit/Difficulty.java

@@ -9,22 +9,27 @@
  */
 public enum Difficulty {
     /**
-     * Players regain health over time, hostile mobs don't spawn, the hunger bar does not deplete.
+     * Players regain health over time, hostile mobs don't spawn, the hunger
+     * bar does not deplete.
      */
     PEACEFUL(0),
 
     /**
-     * Hostile mobs spawn, enemies deal less damage than on normal difficulty, the hunger bar does deplete and starving deals up to 5 hearts of damage. (Default value)
+     * Hostile mobs spawn, enemies deal less damage than on normal difficulty,
+     * the hunger bar does deplete and starving deals up to 5 hearts of
+     * damage. (Default value)
      */
     EASY(1),
 
     /**
-     * Hostile mobs spawn, enemies deal normal amounts of damage, the hunger bar does deplete and starving deals up to 9.5 hearts of damage.
+     * Hostile mobs spawn, enemies deal normal amounts of damage, the hunger
+     * bar does deplete and starving deals up to 9.5 hearts of damage.
      */
     NORMAL(2),
 
     /**
-     * Hostile mobs spawn, enemies deal greater damage than on normal difficulty, the hunger bar does deplete and starving can kill players.
+     * Hostile mobs spawn, enemies deal greater damage than on normal
+     * difficulty, the hunger bar does deplete and starving can kill players.
      */
     HARD(3);
 
@@ -50,7 +55,8 @@ public int getValue() {
      * Gets the Difficulty represented by the specified value
      *
      * @param value Value to check
-     * @return Associative {@link Difficulty} with the given value, or null if it doesn't exist
+     * @return Associative {@link Difficulty} with the given value, or null if
+     *     it doesn't exist
      * @deprecated Magic value
      */
     @Deprecated

src/main/java/org/bukkit/DyeColor.java

@@ -94,7 +94,8 @@ private DyeColor(final int woolData, final int dyeData, Color color, Color firew
      * Gets the associated (wool) data value representing this color.
      *
      * @return A byte containing the (wool) data value of this color
-     * @deprecated The name is misleading. It would imply {@link Material#INK_SACK} but uses {@link Material#WOOL}
+     * @deprecated The name is misleading. It would imply {@link
+     *     Material#INK_SACK} but uses {@link Material#WOOL}
      * @see #getWoolData()
      * @see #getDyeData()
      */
@@ -149,8 +150,10 @@ public Color getFireworkColor() {
      * Gets the DyeColor with the given (wool) data value.
      *
      * @param data (wool) data value to fetch
-     * @return The {@link DyeColor} representing the given value, or null if it doesn't exist
-     * @deprecated The name is misleading. It would imply {@link Material#INK_SACK} but uses {@link Material#WOOL}
+     * @return The {@link DyeColor} representing the given value, or null if
+     *     it doesn't exist
+     * @deprecated The name is misleading. It would imply {@link
+     *     Material#INK_SACK} but uses {@link Material#WOOL}
      * @see #getByDyeData(byte)
      * @see #getByWoolData(byte)
      */
@@ -163,7 +166,8 @@ public static DyeColor getByData(final byte data) {
      * Gets the DyeColor with the given wool data value.
      *
      * @param data Wool data value to fetch
-     * @return The {@link DyeColor} representing the given value, or null if it doesn't exist
+     * @return The {@link DyeColor} representing the given value, or null if
+     *     it doesn't exist
      * @see #getByDyeData(byte)
      * @deprecated Magic value
      */
@@ -180,7 +184,8 @@ public static DyeColor getByWoolData(final byte data) {
      * Gets the DyeColor with the given dye data value.
      *
      * @param data Dye data value to fetch
-     * @return The {@link DyeColor} representing the given value, or null if it doesn't exist
+     * @return The {@link DyeColor} representing the given value, or null if
+     *     it doesn't exist
      * @see #getByWoolData(byte)
      * @deprecated Magic value
      */
@@ -197,7 +202,8 @@ public static DyeColor getByDyeData(final byte data) {
      * Gets the DyeColor with the given color value
      *
      * @param color Color value to get the dye by
-     * @return The {@link DyeColor} representing the given value, or null if it doesn't exist
+     * @return The {@link DyeColor} representing the given value, or null if
+     *     it doesn't exist
      */
     public static DyeColor getByColor(final Color color) {
         return BY_COLOR.get(color);
@@ -207,7 +213,8 @@ public static DyeColor getByColor(final Color color) {
      * Gets the DyeColor with the given firework color value
      *
      * @param color Color value to get dye by
-     * @return The {@link DyeColor} representing the given value, or null if it doesn't exist
+     * @return The {@link DyeColor} representing the given value, or null if
+     *     it doesn't exist
      */
     public static DyeColor getByFireworkColor(final Color color) {
         return BY_FIREWORK.get(color);

src/main/java/org/bukkit/Effect.java

@@ -68,7 +68,8 @@ public enum Effect {
      */
     STEP_SOUND(2001, Type.SOUND, Material.class),
     /**
-     * Visual effect of a splash potion breaking. Needs potion data value as additional info.
+     * Visual effect of a splash potion breaking. Needs potion data value as
+     * additional info.
      */
     POTION_BREAK(2002, Type.VISUAL, Potion.class),
     /**
@@ -114,7 +115,8 @@ public Type getType() {
     }
 
     /**
-     * @return The class which represents data for this effect, or null if none
+     * @return The class which represents data for this effect, or null if
+     *     none
      */
     public Class<?> getData() {
         return this.data;

src/main/java/org/bukkit/EntityEffect.java

@@ -69,7 +69,8 @@ public byte getData() {
      * Gets the EntityEffect with the given data value
      *
      * @param data Data value to fetch
-     * @return The {@link EntityEffect} representing the given value, or null if it doesn't exist
+     * @return The {@link EntityEffect} representing the given value, or null
+     *     if it doesn't exist
      * @deprecated Magic value
      */
     @Deprecated