diff options
310 files changed, 4220 insertions, 2906 deletions
diff --git a/src/main/java/org/bukkit/Achievement.java b/src/main/java/org/bukkit/Achievement.java index aa4e9865..fc914d79 100644 --- a/src/main/java/org/bukkit/Achievement.java +++ b/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 diff --git a/src/main/java/org/bukkit/BlockChangeDelegate.java b/src/main/java/org/bukkit/BlockChangeDelegate.java index 8a439935..e6b9f0e6 100644 --- a/src/main/java/org/bukkit/BlockChangeDelegate.java +++ b/src/main/java/org/bukkit/BlockChangeDelegate.java @@ -8,8 +8,11 @@ package org.bukkit; 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 diff --git a/src/main/java/org/bukkit/Bukkit.java b/src/main/java/org/bukkit/Bukkit.java index 7fd85e79..1014274e 100644 --- a/src/main/java/org/bukkit/Bukkit.java +++ b/src/main/java/org/bukkit/Bukkit.java @@ -574,7 +574,8 @@ public final class Bukkit { } /** - * @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); diff --git a/src/main/java/org/bukkit/ChatColor.java b/src/main/java/org/bukkit/ChatColor.java index 6082c624..0bbc9fac 100644 --- a/src/main/java/org/bukkit/ChatColor.java +++ b/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 enum ChatColor { * 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 enum ChatColor { * 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 enum ChatColor { } /** - * 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. diff --git a/src/main/java/org/bukkit/Chunk.java b/src/main/java/org/bukkit/Chunk.java index 77651392..05101517 100644 --- a/src/main/java/org/bukkit/Chunk.java +++ b/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); diff --git a/src/main/java/org/bukkit/ChunkSnapshot.java b/src/main/java/org/bukkit/ChunkSnapshot.java index 289df00f..83fccc85 100644 --- a/src/main/java/org/bukkit/ChunkSnapshot.java +++ b/src/main/java/org/bukkit/ChunkSnapshot.java @@ -3,8 +3,10 @@ package org.bukkit; 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 diff --git a/src/main/java/org/bukkit/CoalType.java b/src/main/java/org/bukkit/CoalType.java index 9eb0231c..4fcccd21 100644 --- a/src/main/java/org/bukkit/CoalType.java +++ b/src/main/java/org/bukkit/CoalType.java @@ -32,10 +32,9 @@ public enum CoalType { /** * 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 diff --git a/src/main/java/org/bukkit/Color.java b/src/main/java/org/bukkit/Color.java index b544af20..76ff651f 100644 --- a/src/main/java/org/bukkit/Color.java +++ b/src/main/java/org/bukkit/Color.java @@ -9,8 +9,9 @@ import org.bukkit.configuration.serialization.SerializableAs; 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,11 +133,13 @@ public final class Color implements ConfigurationSerializable { } /** - * 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); @@ -144,11 +147,13 @@ public final class Color implements ConfigurationSerializable { } /** - * 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 final class Color implements ConfigurationSerializable { } /** - * 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 final class Color implements ConfigurationSerializable { } /** - * 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 diff --git a/src/main/java/org/bukkit/CropState.java b/src/main/java/org/bukkit/CropState.java index 8f2e62b8..ef0faf93 100644 --- a/src/main/java/org/bukkit/CropState.java +++ b/src/main/java/org/bukkit/CropState.java @@ -63,10 +63,9 @@ public enum CropState { /** * 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 diff --git a/src/main/java/org/bukkit/Difficulty.java b/src/main/java/org/bukkit/Difficulty.java index 3463f981..a8a5a785 100644 --- a/src/main/java/org/bukkit/Difficulty.java +++ b/src/main/java/org/bukkit/Difficulty.java @@ -9,22 +9,27 @@ import com.google.common.collect.Maps; */ 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 enum Difficulty { * 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 diff --git a/src/main/java/org/bukkit/DyeColor.java b/src/main/java/org/bukkit/DyeColor.java index d968a65d..2c2f3ca6 100644 --- a/src/main/java/org/bukkit/DyeColor.java +++ b/src/main/java/org/bukkit/DyeColor.java @@ -94,7 +94,8 @@ public enum DyeColor { * 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 enum DyeColor { * 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 enum DyeColor { * 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 enum DyeColor { * 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 enum DyeColor { * 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 enum DyeColor { * 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); diff --git a/src/main/java/org/bukkit/Effect.java b/src/main/java/org/bukkit/Effect.java index 708bee92..2474a2d9 100644 --- a/src/main/java/org/bukkit/Effect.java +++ b/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 enum Effect { } /** - * @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; diff --git a/src/main/java/org/bukkit/EntityEffect.java b/src/main/java/org/bukkit/EntityEffect.java index ad2c7423..f2481bad 100644 --- a/src/main/java/org/bukkit/EntityEffect.java +++ b/src/main/java/org/bukkit/EntityEffect.java @@ -69,7 +69,8 @@ public enum EntityEffect { * 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 diff --git a/src/main/java/org/bukkit/FireworkEffect.java b/src/main/java/org/bukkit/FireworkEffect.java index ac89ba11..6f2d0968 100644 --- a/src/main/java/org/bukkit/FireworkEffect.java +++ b/src/main/java/org/bukkit/FireworkEffect.java @@ -142,7 +142,8 @@ public final class FireworkEffect implements ConfigurationSerializable { * @param colors The colors to add * @return This object, for chaining * @throws IllegalArgumentException If colors is null - * @throws IllegalArgumentException If any color is null (may be thrown after changes have occurred) + * @throws IllegalArgumentException If any color is null (may be + * thrown after changes have occurred) */ public Builder withColor(Color...colors) throws IllegalArgumentException { Validate.notNull(colors, "Cannot have null colors"); @@ -162,10 +163,12 @@ public final class FireworkEffect implements ConfigurationSerializable { /** * Add several primary colors to the firework effect. * - * @param colors An iterable object whose iterator yields the desired colors + * @param colors An iterable object whose iterator yields the desired + * colors * @return This object, for chaining * @throws IllegalArgumentException If colors is null - * @throws IllegalArgumentException If any color is null (may be thrown after changes have occurred) + * @throws IllegalArgumentException If any color is null (may be + * thrown after changes have occurred) */ public Builder withColor(Iterable<?> colors) throws IllegalArgumentException { Validate.notNull(colors, "Cannot have null colors"); @@ -187,7 +190,8 @@ public final class FireworkEffect implements ConfigurationSerializable { * @param color The color to add * @return This object, for chaining * @throws IllegalArgumentException If colors is null - * @throws IllegalArgumentException If any color is null (may be thrown after changes have occurred) + * @throws IllegalArgumentException If any color is null (may be + * thrown after changes have occurred) */ public Builder withFade(Color color) throws IllegalArgumentException { Validate.notNull(color, "Cannot have null color"); @@ -207,7 +211,8 @@ public final class FireworkEffect implements ConfigurationSerializable { * @param colors The colors to add * @return This object, for chaining * @throws IllegalArgumentException If colors is null - * @throws IllegalArgumentException If any color is null (may be thrown after changes have occurred) + * @throws IllegalArgumentException If any color is null (may be + * thrown after changes have occurred) */ public Builder withFade(Color...colors) throws IllegalArgumentException { Validate.notNull(colors, "Cannot have null colors"); @@ -231,10 +236,12 @@ public final class FireworkEffect implements ConfigurationSerializable { /** * Add several fade colors to the firework effect. * - * @param colors An iterable object whose iterator yields the desired colors + * @param colors An iterable object whose iterator yields the desired + * colors * @return This object, for chaining * @throws IllegalArgumentException If colors is null - * @throws IllegalArgumentException If any color is null (may be thrown after changes have occurred) + * @throws IllegalArgumentException If any color is null (may be + * thrown after changes have occurred) */ public Builder withFade(Iterable<?> colors) throws IllegalArgumentException { Validate.notNull(colors, "Cannot have null colors"); @@ -255,7 +262,9 @@ public final class FireworkEffect implements ConfigurationSerializable { } /** - * Create a {@link FireworkEffect} from the current contents of this builder. + * Create a {@link FireworkEffect} from the current contents of this + * builder. + * <p> * To successfully build, you must have specified at least one color. * * @return The representative firework effect diff --git a/src/main/java/org/bukkit/GameMode.java b/src/main/java/org/bukkit/GameMode.java index 5b83d88f..47b2d90b 100644 --- a/src/main/java/org/bukkit/GameMode.java +++ b/src/main/java/org/bukkit/GameMode.java @@ -7,11 +7,13 @@ import org.bukkit.entity.HumanEntity; import com.google.common.collect.Maps; /** - * Represents the various type of game modes that {@link HumanEntity}s may have + * Represents the various type of game modes that {@link HumanEntity}s may + * have */ public enum GameMode { /** - * Creative mode may fly, build instantly, become invulnerable and create free items. + * Creative mode may fly, build instantly, become invulnerable and create + * free items. */ CREATIVE(1), @@ -47,7 +49,8 @@ public enum GameMode { * Gets the GameMode represented by the specified value * * @param value Value to check - * @return Associative {@link GameMode} with the given value, or null if it doesn't exist + * @return Associative {@link GameMode} with the given value, or null if + * it doesn't exist * @deprecated Magic value */ @Deprecated diff --git a/src/main/java/org/bukkit/GrassSpecies.java b/src/main/java/org/bukkit/GrassSpecies.java index c2b0aeb3..11115157 100644 --- a/src/main/java/org/bukkit/GrassSpecies.java +++ b/src/main/java/org/bukkit/GrassSpecies.java @@ -43,10 +43,9 @@ public enum GrassSpecies { /** * Gets the GrassSpecies with the given data value * - * @param data - * Data value to fetch - * @return The {@link GrassSpecies} representing the given value, or null if - * it doesn't exist + * @param data Data value to fetch + * @return The {@link GrassSpecies} representing the given value, or null + * if it doesn't exist * @deprecated Magic value */ @Deprecated diff --git a/src/main/java/org/bukkit/Instrument.java b/src/main/java/org/bukkit/Instrument.java index dc7b4a0e..891a2b1b 100644 --- a/src/main/java/org/bukkit/Instrument.java +++ b/src/main/java/org/bukkit/Instrument.java @@ -11,19 +11,23 @@ public enum Instrument { */ PIANO(0x0), /** - * Bass drum is normally played when a note block is on top of a stone-like block + * Bass drum is normally played when a note block is on top of a + * stone-like block */ BASS_DRUM(0x1), /** - * Snare drum is normally played when a note block is on top of a sandy block. + * Snare drum is normally played when a note block is on top of a sandy + * block. */ SNARE_DRUM(0x2), /** - * Sticks are normally played when a note block is on top of a glass block. + * Sticks are normally played when a note block is on top of a glass + * block. */ STICKS(0x3), /** - * Bass guitar is normally played when a note block is on top of a wooden block. + * Bass guitar is normally played when a note block is on top of a wooden + * block. */ BASS_GUITAR(0x4); diff --git a/src/main/java/org/bukkit/Location.java b/src/main/java/org/bukkit/Location.java index 0f74f6d4..9e1e6045 100644 --- a/src/main/java/org/bukkit/Location.java +++ b/src/main/java/org/bukkit/Location.java @@ -390,12 +390,12 @@ public class Location implements Cloneable { } /** - * Gets the magnitude of the location, defined as sqrt(x^2+y^2+z^2). The value - * of this method is not cached and uses a costly square-root function, so - * do not repeatedly call this method to get the location's magnitude. NaN - * will be returned if the inner result of the sqrt() function overflows, - * which will be caused if the length is too long. Not world-aware and - * orientation independent. + * Gets the magnitude of the location, defined as sqrt(x^2+y^2+z^2). The + * value of this method is not cached and uses a costly square-root + * function, so do not repeatedly call this method to get the location's + * magnitude. NaN will be returned if the inner result of the sqrt() + * function overflows, which will be caused if the length is too long. Not + * world-aware and orientation independent. * * @see Vector * @return the magnitude @@ -416,11 +416,11 @@ public class Location implements Cloneable { } /** - * Get the distance between this location and another. The value - * of this method is not cached and uses a costly square-root function, so - * do not repeatedly call this method to get the location's magnitude. NaN - * will be returned if the inner result of the sqrt() function overflows, - * which will be caused if the distance is too long. + * Get the distance between this location and another. The value of this + * method is not cached and uses a costly square-root function, so do not + * repeatedly call this method to get the location's magnitude. NaN will + * be returned if the inner result of the sqrt() function overflows, which + * will be caused if the distance is too long. * * @see Vector * @param o The other location @@ -452,8 +452,8 @@ public class Location implements Cloneable { } /** - * Performs scalar multiplication, multiplying all components with a scalar. - * Not world-aware. + * Performs scalar multiplication, multiplying all components with a + * scalar. Not world-aware. * * @param m The factor * @see Vector @@ -531,7 +531,8 @@ public class Location implements Cloneable { /** * Constructs a new {@link Vector} based on this Location * - * @return New Vector containing the coordinates represented by this Location + * @return New Vector containing the coordinates represented by this + * Location */ public Vector toVector() { return new Vector(x, y, z); @@ -547,7 +548,8 @@ public class Location implements Cloneable { } /** - * Safely converts a double (location coordinate) to an int (block coordinate) + * Safely converts a double (location coordinate) to an int (block + * coordinate) * * @param loc Precise coordinate * @return Block coordinate diff --git a/src/main/java/org/bukkit/Material.java b/src/main/java/org/bukkit/Material.java index 338fd569..576d984c 100644 --- a/src/main/java/org/bukkit/Material.java +++ b/src/main/java/org/bukkit/Material.java @@ -495,8 +495,8 @@ public enum Material { } /** - * Constructs a new MaterialData relevant for this Material, with the given - * initial data + * Constructs a new MaterialData relevant for this Material, with the + * given initial data * * @param raw Initial data to construct the MaterialData with * @return New MaterialData with the given data @@ -582,6 +582,7 @@ public enum Material { /** * Attempts to get the Material with the given name. + * <p> * This is a normal lookup, names must be the precise name they are given * in the enum. * @@ -594,8 +595,10 @@ public enum Material { /** * Attempts to match the Material with the given name. - * This is a match lookup; names will be converted to uppercase, then stripped - * of special characters in an attempt to format it like the enum. + * <p> + * This is a match lookup; names will be converted to uppercase, then + * stripped of special characters in an attempt to format it like the + * enum. * <p> * Using this for match by ID is deprecated. * @@ -641,7 +644,8 @@ public enum Material { } /** - * Check if the material is a block and solid (cannot be passed through by a player) + * Check if the material is a block and solid (cannot be passed through by + * a player) * * @return True if this material is a block and solid */ diff --git a/src/main/java/org/bukkit/NetherWartsState.java b/src/main/java/org/bukkit/NetherWartsState.java index ae557e80..f43209cf 100644 --- a/src/main/java/org/bukkit/NetherWartsState.java +++ b/src/main/java/org/bukkit/NetherWartsState.java @@ -1,20 +1,21 @@ -package org.bukkit;
-
-public enum NetherWartsState {
- /**
- * State when first seeded
- */
- SEEDED,
- /**
- * First growth stage
- */
- STAGE_ONE,
- /**
- * Second growth stage
- */
- STAGE_TWO,
- /**
- * Ready to harvest
- */
- RIPE;
-}
+package org.bukkit; + +public enum NetherWartsState { + + /** + * State when first seeded + */ + SEEDED, + /** + * First growth stage + */ + STAGE_ONE, + /** + * Second growth stage + */ + STAGE_TWO, + /** + * Ready to harvest + */ + RIPE; +} diff --git a/src/main/java/org/bukkit/Note.java b/src/main/java/org/bukkit/Note.java index 3a41ea49..417936fa 100644 --- a/src/main/java/org/bukkit/Note.java +++ b/src/main/java/org/bukkit/Note.java @@ -76,7 +76,8 @@ public class Note { * * @param id the id of the tone. * @return if the tone id is the sharped id of the tone. - * @throws IllegalArgumentException if neither the tone nor the semitone have the id. + * @throws IllegalArgumentException if neither the tone nor the + * semitone have the id. * @deprecated Magic value */ @Deprecated @@ -121,8 +122,8 @@ public class Note { /** * Creates a new note. * - * @param note Internal note id. {@link #getId()} always return this value. - * The value has to be in the interval [0; 24]. + * @param note Internal note id. {@link #getId()} always return this + * value. The value has to be in the interval [0; 24]. */ public Note(int note) { Validate.isTrue(note >= 0 && note <= 24, "The note value has to be between 0 and 24."); @@ -134,7 +135,8 @@ public class Note { * Creates a new note. * * @param octave The octave where the note is in. Has to be 0 - 2. - * @param tone The tone within the octave. If the octave is 2 the note has to be F#. + * @param tone The tone within the octave. If the octave is 2 the note has + * to be F#. * @param sharped Set if the tone is sharped (e.g. for F#). */ public Note(int octave, Tone tone, boolean sharped) { @@ -166,7 +168,8 @@ public class Note { * Creates a new note for a sharp tone, such as A-sharp. * * @param octave The octave where the note is in. Has to be 0 - 2. - * @param tone The tone within the octave. If the octave is 2 the note has to be F#. + * @param tone The tone within the octave. If the octave is 2 the note has + * to be F#. * @return The new note. */ public static Note sharp(int octave, Tone tone) { diff --git a/src/main/java/org/bukkit/OfflinePlayer.java b/src/main/java/org/bukkit/OfflinePlayer.java index bf6682bb..21d13c3b 100644 --- a/src/main/java/org/bukkit/OfflinePlayer.java +++ b/src/main/java/org/bukkit/OfflinePlayer.java @@ -60,20 +60,24 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio public Player getPlayer(); /** - * Gets the first date and time that this player was witnessed on this server. + * Gets the first date and time that this player was witnessed on this + * server. * <p> - * If the player has never played before, this will return 0. Otherwise, it will be - * the amount of milliseconds since midnight, January 1, 1970 UTC. + * If the player has never played before, this will return 0. Otherwise, + * it will be the amount of milliseconds since midnight, January 1, 1970 + * UTC. * * @return Date of first log-in for this player, or 0 */ public long getFirstPlayed(); /** - * Gets the last date and time that this player was witnessed on this server. + * Gets the last date and time that this player was witnessed on this + * server. * <p> - * If the player has never played before, this will return 0. Otherwise, it will be - * the amount of milliseconds since midnight, January 1, 1970 UTC. + * If the player has never played before, this will return 0. Otherwise, + * it will be the amount of milliseconds since midnight, January 1, 1970 + * UTC. * * @return Date of last log-in for this player, or 0 */ @@ -87,8 +91,8 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio public boolean hasPlayedBefore(); /** - * Gets the Location where the player will spawn at their bed, null if they - * have not slept in one or their current bed spawn is invalid. + * Gets the Location where the player will spawn at their bed, null if + * they have not slept in one or their current bed spawn is invalid. * * @return Bed Spawn Location if bed exists, otherwise null. */ diff --git a/src/main/java/org/bukkit/PortalType.java b/src/main/java/org/bukkit/PortalType.java index a63dad23..427cfbb8 100644 --- a/src/main/java/org/bukkit/PortalType.java +++ b/src/main/java/org/bukkit/PortalType.java @@ -4,6 +4,7 @@ package org.bukkit; * Represents various types of portals that can be made in a world. */ public enum PortalType { + /** * This is a Nether portal, made of obsidian. */ diff --git a/src/main/java/org/bukkit/Rotation.java b/src/main/java/org/bukkit/Rotation.java index 90df0097..dfdb0e5a 100644 --- a/src/main/java/org/bukkit/Rotation.java +++ b/src/main/java/org/bukkit/Rotation.java @@ -2,6 +2,7 @@ package org.bukkit; /** * An enum to specify a rotation based orientation, like that on a clock. + * <p> * It represents how something is viewed, as opposed to cardinal directions. */ public enum Rotation { diff --git a/src/main/java/org/bukkit/SandstoneType.java b/src/main/java/org/bukkit/SandstoneType.java index cba1c2a8..a9ac16e7 100644 --- a/src/main/java/org/bukkit/SandstoneType.java +++ b/src/main/java/org/bukkit/SandstoneType.java @@ -33,10 +33,9 @@ public enum SandstoneType { /** * Gets the type of sandstone with the given data value * - * @param data - * Data value to fetch - * @return The {@link SandstoneType} representing the given value, or null if - * it doesn't exist + * @param data Data value to fetch + * @return The {@link SandstoneType} representing the given value, or null + * if it doesn't exist * @deprecated Magic value */ @Deprecated diff --git a/src/main/java/org/bukkit/Server.java b/src/main/java/org/bukkit/Server.java index 0e789315..1eb32b78 100644 --- a/src/main/java/org/bukkit/Server.java +++ b/src/main/java/org/bukkit/Server.java @@ -41,14 +41,16 @@ import org.bukkit.inventory.meta.ItemMeta; public interface Server extends PluginMessageRecipient { /** - * Used for all administrative messages, such as an operator using a command. + * Used for all administrative messages, such as an operator using a + * command. * <p> * For use in {@link #broadcast(java.lang.String, java.lang.String)} */ public static final String BROADCAST_CHANNEL_ADMINISTRATIVE = "bukkit.broadcast.admin"; /** - * Used for all announcement messages, such as informing users that a player has joined. + * Used for all announcement messages, such as informing users that a + * player has joined. * <p> * For use in {@link #broadcast(java.lang.String, java.lang.String)} */ @@ -104,9 +106,11 @@ public interface Server extends PluginMessageRecipient { public int getViewDistance(); /** - * Get the IP that this server is bound to or empty string if not specified + * Get the IP that this server is bound to or empty string if not + * specified * - * @return The IP string that this server is bound to, otherwise empty string + * @return The IP string that this server is bound to, otherwise empty + * string */ public String getIp(); @@ -118,8 +122,8 @@ public interface Server extends PluginMessageRecipient { public String getServerName(); /** - * Get an ID of this server. The ID is a simple generally alphanumeric - * ID that can be used for uniquely identifying this server. + * Get an ID of this server. The ID is a simple generally alphanumeric ID + * that can be used for uniquely identifying this server. * * @return The ID of this server */ @@ -182,7 +186,8 @@ public interface Server extends PluginMessageRecipient { /** * Broadcast a message to all players. * <p> - * This is the same as calling {@link #broadcast(java.lang.String, java.lang.String)} to {@link #BROADCAST_CHANNEL_USERS} + * This is the same as calling {@link #broadcast(java.lang.String, + * java.lang.String)} to {@link #BROADCAST_CHANNEL_USERS} * * @param message the message * @return the number of players @@ -190,8 +195,8 @@ public interface Server extends PluginMessageRecipient { public int broadcastMessage(String message); /** - * Gets the name of the update folder. The update folder is used to safely update - * plugins at the right moment on a plugin load. + * Gets the name of the update folder. The update folder is used to safely + * update plugins at the right moment on a plugin load. * <p> * The update folder name is relative to the plugins folder. * @@ -219,13 +224,15 @@ public interface Server extends PluginMessageRecipient { * <p> * <b>Example Usage:</b> * <ul> - * <li>A value of 1 will mean the server will attempt to spawn monsters every tick. - * <li>A value of 400 will mean the server will attempt to spawn monsters every 400th tick. + * <li>A value of 1 will mean the server will attempt to spawn monsters + * every tick. + * <li>A value of 400 will mean the server will attempt to spawn monsters + * every 400th tick. * <li>A value below 0 will be reset back to Minecraft's default. * </ul> * <p> - * <b>Note:</b> - * If set to 0, animal spawning will be disabled. We recommend using spawn-animals to control this instead. + * <b>Note:</b> If set to 0, animal spawning will be disabled. We + * recommend using spawn-animals to control this instead. * <p> * Minecraft default: 400. * @@ -238,13 +245,15 @@ public interface Server extends PluginMessageRecipient { * <p> * <b>Example Usage:</b> * <ul> - * <li>A value of 1 will mean the server will attempt to spawn monsters every tick. - * <li>A value of 400 will mean the server will attempt to spawn monsters every 400th tick. + * <li>A value of 1 will mean the server will attempt to spawn monsters + * every tick. + * <li>A value of 400 will mean the server will attempt to spawn monsters + * every 400th tick. * <li>A value below 0 will be reset back to Minecraft's default. * </ul> * <p> - * <b>Note:</b> - * If set to 0, monsters spawning will be disabled. We recommend using spawn-monsters to control this instead. + * <b>Note:</b> If set to 0, monsters spawning will be disabled. We + * recommend using spawn-monsters to control this instead. * <p> * Minecraft default: 1. * @@ -274,8 +283,8 @@ public interface Server extends PluginMessageRecipient { * Attempts to match any players with the given name, and returns a list * of all possibly matches * <p> - * This list is not sorted in any particular order. If an exact match is found, - * the returned list will only contain a single result. + * This list is not sorted in any particular order. If an exact match is + * found, the returned list will only contain a single result. * * @param name Name to match * @return List of all possible players @@ -311,7 +320,8 @@ public interface Server extends PluginMessageRecipient { public List<World> getWorlds(); /** - * Creates or loads a world with the given name using the specified options. + * Creates or loads a world with the given name using the specified + * options. * <p> * If the world is already loaded, it will just return the equivalent of * getWorld(creator.name()). @@ -404,12 +414,14 @@ public interface Server extends PluginMessageRecipient { * @param sender The apparent sender of the command * @param commandLine command + arguments. Example: "test abc 123" * @return returns false if no target is found. - * @throws CommandException Thrown when the executor for the given command fails with an unhandled exception + * @throws CommandException Thrown when the executor for the given command + * fails with an unhandled exception */ public boolean dispatchCommand(CommandSender sender, String commandLine) throws CommandException; /** - * Populates a given {@link ServerConfig} with values attributes to this server + * Populates a given {@link ServerConfig} with values attributes to this + * server * * @param config ServerConfig to populate */ @@ -419,13 +431,14 @@ public interface Server extends PluginMessageRecipient { * Adds a recipe to the crafting manager. * * @param recipe The recipe to add. - * @return True if the recipe was added, false if it wasn't for some reason. + * @return True if the recipe was added, false if it wasn't for some + * reason. */ public boolean addRecipe(Recipe recipe); /** - * Get a list of all recipes for a given item. The stack size is ignored in comparisons. - * If the durability is -1, it will match any data value. + * Get a list of all recipes for a given item. The stack size is ignored + * in comparisons. If the durability is -1, it will match any data value. * * @param result The item whose recipes you want * @return The list of recipes @@ -494,8 +507,11 @@ public interface Server extends PluginMessageRecipient { /** * Gets whether to use vanilla (false) or exact behaviour (true). * - * Vanilla behaviour: check for collisions and move the player if needed. - * Exact behaviour: spawn players exactly where they should be. + * <ul> + * <li>Vanilla behaviour: check for collisions and move the player if + * needed. + * <li>Exact behaviour: spawn players exactly where they should be. + * </ul> * * @return Whether to use vanilla (false) or exact behaviour (true). */ @@ -507,7 +523,8 @@ public interface Server extends PluginMessageRecipient { public void shutdown(); /** - * Broadcasts the specified message to every user with the given permission + * Broadcasts the specified message to every user with the given + * permission * * @param message Message to broadcast * @param permission Permission the users must have to receive the broadcast @@ -516,9 +533,11 @@ public interface Server extends PluginMessageRecipient { public int broadcast(String message, String permission); /** - * Gets the player by the given name, regardless if they are offline or online. + * Gets the player by the given name, regardless if they are offline or + * online. * <p> - * This will return an object even if the player does not exist. To this method, all players will exist. + * This will return an object even if the player does not exist. To this + * method, all players will exist. * * @param name Name of the player to retrieve * @return OfflinePlayer object @@ -575,8 +594,8 @@ public interface Server extends PluginMessageRecipient { public void setDefaultGameMode(GameMode mode); /** - * Gets the {@link ConsoleCommandSender} that may be used as an input source - * for this server. + * Gets the {@link ConsoleCommandSender} that may be used as an input + * source for this server. * * @return The Console CommandSender */ @@ -611,20 +630,23 @@ public interface Server extends PluginMessageRecipient { public HelpMap getHelpMap(); /** - * Creates an empty inventory of the specified type. If the type is {@link InventoryType#CHEST}, - * the new inventory has a size of 27; otherwise the new inventory has the normal size for - * its type. + * Creates an empty inventory of the specified type. If the type is {@link + * InventoryType#CHEST}, the new inventory has a size of 27; otherwise the + * new inventory has the normal size for its type. * - * @param owner The holder of the inventory; can be null if there's no holder. + * @param owner The holder of the inventory; can be null if there's no + * holder. * @param type The type of inventory to create. * @return The new inventory. */ Inventory createInventory(InventoryHolder owner, InventoryType type); /** - * Creates an empty inventory of type {@link InventoryType#CHEST} with the specified size. + * Creates an empty inventory of type {@link InventoryType#CHEST} with the + * specified size. * - * @param owner The holder of the inventory; can be null if there's no holder. + * @param owner The holder of the inventory; can be null if there's no + * holder. * @param size The size of inventory to create; must be a multiple of 9. * @return The new inventory. * @throws IllegalArgumentException If the size is not a multiple of 9. @@ -632,46 +654,54 @@ public interface Server extends PluginMessageRecipient { Inventory createInventory(InventoryHolder owner, int size); /** - * Creates an empty inventory of type {@link InventoryType#CHEST} with the specified size and title. + * Creates an empty inventory of type {@link InventoryType#CHEST} with the + * specified size and title. * - * @param owner The holder of the inventory; can be null if there's no holder. + * @param owner The holder of the inventory; can be null if there's no + * holder. * @param size The size of inventory to create; must be a multiple of 9. - * @param title The title of the inventory, to be displayed when it is viewed. + * @param title The title of the inventory, to be displayed when it is + * viewed. * @return The new inventory. * @throws IllegalArgumentException If the size is not a multiple of 9. */ Inventory createInventory(InventoryHolder owner, int size, String title); /** - * Gets user-specified limit for number of monsters that can spawn in a chunk + * Gets user-specified limit for number of monsters that can spawn in a + * chunk * * @return The monster spawn limit */ int getMonsterSpawnLimit(); /** - * Gets user-specified limit for number of animals that can spawn in a chunk + * Gets user-specified limit for number of animals that can spawn in a + * chunk * * @return The animal spawn limit */ int getAnimalSpawnLimit(); /** - * Gets user-specified limit for number of water animals that can spawn in a chunk + * Gets user-specified limit for number of water animals that can spawn in + * a chunk * * @return The water animal spawn limit */ int getWaterAnimalSpawnLimit(); /** - * Gets user-specified limit for number of ambient mobs that can spawn in a chunk + * Gets user-specified limit for number of ambient mobs that can spawn in + * a chunk * * @return The ambient spawn limit */ int getAmbientSpawnLimit(); /** - * Returns true if the current {@link Thread} is the server's primary thread + * Returns true if the current {@link Thread} is the server's primary + * thread */ boolean isPrimaryThread(); @@ -723,16 +753,16 @@ public interface Server extends PluginMessageRecipient { CachedServerIcon getServerIcon(); /** - * Loads an image from a file, and returns a cached image for the - * specific server-icon. + * Loads an image from a file, and returns a cached image for the specific + * server-icon. * <p> * Size and type are implementation defined. An incompatible file is * guaranteed to throw an implementation-defined {@link Exception}. * * @param file the file to load the from * @throws IllegalArgumentException if image is null - * @throws Exception if the image does not meet current server - * server-icon specifications + * @throws Exception if the image does not meet current server server-icon + * specifications * @return a cached server-icon that can be used for a {@link * ServerListPingEvent#setServerIcon(CachedServerIcon)} */ diff --git a/src/main/java/org/bukkit/Sound.java b/src/main/java/org/bukkit/Sound.java index 90d40394..77261c28 100644 --- a/src/main/java/org/bukkit/Sound.java +++ b/src/main/java/org/bukkit/Sound.java @@ -3,8 +3,10 @@ package org.bukkit; /** * An Enum of Sounds the server is able to send to players. * <p> - * WARNING: At any time, sounds may be added/removed from this Enum or even MineCraft itself! There is no guarantee the sounds will play. - * There is no guarantee values will not be removed from this Enum. As such, you should not depend on the ordinal values of this class. + * WARNING: At any time, sounds may be added/removed from this Enum or even + * MineCraft itself! There is no guarantee the sounds will play. There is no + * guarantee values will not be removed from this Enum. As such, you should + * not depend on the ordinal values of this class. */ public enum Sound { AMBIENCE_CAVE, diff --git a/src/main/java/org/bukkit/Statistic.java b/src/main/java/org/bukkit/Statistic.java index 33e851ad..4532123a 100644 --- a/src/main/java/org/bukkit/Statistic.java +++ b/src/main/java/org/bukkit/Statistic.java @@ -33,7 +33,8 @@ public enum Statistic { /** * Checks if this is a substatistic. * <p> - * A substatistic exists in mass for each block or item, depending on {@link #isBlock()} + * A substatistic exists in mass for each block or item, depending on + * {@link #isBlock()} * * @return true if this is a substatistic */ @@ -42,7 +43,8 @@ public enum Statistic { } /** - * Checks if this is a substatistic dealing with blocks (As opposed to items) + * Checks if this is a substatistic dealing with blocks (As opposed to + * items) * * @return true if this deals with blocks, false if with items */ diff --git a/src/main/java/org/bukkit/TreeSpecies.java b/src/main/java/org/bukkit/TreeSpecies.java index de5e7461..f29062ac 100644 --- a/src/main/java/org/bukkit/TreeSpecies.java +++ b/src/main/java/org/bukkit/TreeSpecies.java @@ -57,8 +57,8 @@ public enum TreeSpecies { * Gets the TreeSpecies with the given data value * * @param data Data value to fetch - * @return The {@link TreeSpecies} representing the given value, or null if - * it doesn't exist + * @return The {@link TreeSpecies} representing the given value, or null + * if it doesn't exist * @deprecated Magic value */ @Deprecated diff --git a/src/main/java/org/bukkit/Utility.java b/src/main/java/org/bukkit/Utility.java index 0e54481b..da66853e 100644 --- a/src/main/java/org/bukkit/Utility.java +++ b/src/main/java/org/bukkit/Utility.java @@ -6,8 +6,11 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * This annotation indicates a method (and sometimes constructor) will chain its internal operations. - * This is solely meant for identifying methods that don't need to be overridden / handled manually. + * This annotation indicates a method (and sometimes constructor) will chain + * its internal operations. + * <p> + * This is solely meant for identifying methods that don't need to be + * overridden / handled manually. */ @Target({ElementType.CONSTRUCTOR, ElementType.METHOD}) @Retention(RetentionPolicy.SOURCE) diff --git a/src/main/java/org/bukkit/Warning.java b/src/main/java/org/bukkit/Warning.java index fca77cec..6a2a3b0d 100644 --- a/src/main/java/org/bukkit/Warning.java +++ b/src/main/java/org/bukkit/Warning.java @@ -10,7 +10,9 @@ import com.google.common.collect.ImmutableMap; /** * This designates the warning state for a specific item. - * When the server settings dictate 'default' warnings, warnings are printed if the {@link #value()} is true. + * <p> + * When the server settings dictate 'default' warnings, warnings are printed + * if the {@link #value()} is true. */ @Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) @@ -30,7 +32,8 @@ public @interface Warning { */ OFF, /** - * Indicates each warning would default to the configured {@link Warning} annotation, or always if annotation not found. + * Indicates each warning would default to the configured {@link + * Warning} annotation, or always if annotation not found. */ DEFAULT; @@ -51,12 +54,16 @@ public @interface Warning { .build(); /** - * This method checks the provided warning should be printed for this state + * This method checks the provided warning should be printed for this + * state * * @param warning The warning annotation added to a deprecated item - * @return ON is always True<br> - * OFF is always false<br> - * DEFAULT is false if and only if annotation is not null and specifies false for {@link Warning#value()}, true otherwise. + * @return <ul> + * <li>ON is always True + * <li>OFF is always false + * <li>DEFAULT is false if and only if annotation is not null and + * specifies false for {@link Warning#value()}, true otherwise. + * </ul> */ public boolean printFor(Warning warning) { if (this == DEFAULT) { @@ -66,10 +73,12 @@ public @interface Warning { } /** - * This method returns the corresponding warning state for the given string value. + * This method returns the corresponding warning state for the given + * string value. * * @param value The string value to check - * @return {@link #DEFAULT} if not found, or the respective WarningState + * @return {@link #DEFAULT} if not found, or the respective + * WarningState */ public static WarningState value(final String value) { if (value == null) { @@ -84,7 +93,8 @@ public @interface Warning { } /** - * This sets if the deprecation warnings when registering events gets printed when the setting is in the default state. + * This sets if the deprecation warnings when registering events gets + * printed when the setting is in the default state. * * @return false normally, or true to encourage warning printout */ diff --git a/src/main/java/org/bukkit/WeatherType.java b/src/main/java/org/bukkit/WeatherType.java index 624ed489..36b993f1 100644 --- a/src/main/java/org/bukkit/WeatherType.java +++ b/src/main/java/org/bukkit/WeatherType.java @@ -4,6 +4,7 @@ package org.bukkit; * An enum of all current weather types */ public enum WeatherType { + /** * Raining or snowing depending on biome. */ diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java index 63507c9f..f02bfb74 100644 --- a/src/main/java/org/bukkit/World.java +++ b/src/main/java/org/bukkit/World.java @@ -29,7 +29,8 @@ public interface World extends PluginMessageRecipient, Metadatable { * @param y Y-coordinate of the block * @param z Z-coordinate of the block * @return Block at the given coordinates - * @see #getBlockTypeIdAt(int, int, int) Returns the current type ID of the block + * @see #getBlockTypeIdAt(int, int, int) Returns the current type ID of + * the block */ public Block getBlockAt(int x, int y, int z); @@ -38,7 +39,8 @@ public interface World extends PluginMessageRecipient, Metadatable { * * @param location Location of the block * @return Block at the given location - * @see #getBlockTypeIdAt(org.bukkit.Location) Returns the current type ID of the block + * @see #getBlockTypeIdAt(org.bukkit.Location) Returns the current type ID + * of the block */ public Block getBlockAt(Location location); @@ -49,7 +51,8 @@ public interface World extends PluginMessageRecipient, Metadatable { * @param y Y-coordinate of the block * @param z Z-coordinate of the block * @return Type ID of the block at the given coordinates - * @see #getBlockAt(int, int, int) Returns a live Block object at the given location + * @see #getBlockAt(int, int, int) Returns a live Block object at the + * given location * @deprecated Magic value */ @Deprecated @@ -60,7 +63,8 @@ public interface World extends PluginMessageRecipient, Metadatable { * * @param location Location of the block * @return Type ID of the block at the given location - * @see #getBlockAt(org.bukkit.Location) Returns a live Block object at the given location + * @see #getBlockAt(org.bukkit.Location) Returns a live Block object at + * the given location * @deprecated Magic value */ @Deprecated @@ -157,11 +161,13 @@ public interface World extends PluginMessageRecipient, Metadatable { public boolean isChunkLoaded(int x, int z); /** - * Checks if the {@link Chunk} at the specified coordinates is loaded and in use by one or more players + * Checks if the {@link Chunk} at the specified coordinates is loaded and + * in use by one or more players * * @param x X-coordinate of the chunk * @param z Z-coordinate of the chunk - * @return true if the chunk is loaded and in use by one or more players, otherwise false + * @return true if the chunk is loaded and in use by one or more players, + * otherwise false */ public boolean isChunkInUse(int x, int z); @@ -169,7 +175,9 @@ public interface World extends PluginMessageRecipient, Metadatable { * Loads the {@link Chunk} at the specified coordinates * <p> * If the chunk does not exist, it will be generated. - * This method is analogous to {@link #loadChunk(int, int, boolean)} where generate is true. + * <p> + * This method is analogous to {@link #loadChunk(int, int, boolean)} where + * generate is true. * * @param x X-coordinate of the chunk * @param z Z-coordinate of the chunk @@ -181,7 +189,8 @@ public interface World extends PluginMessageRecipient, Metadatable { * * @param x X-coordinate of the chunk * @param z Z-coordinate of 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 */ public boolean loadChunk(int x, int z, boolean generate); @@ -189,7 +198,8 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Safely unloads and saves the {@link Chunk} at the specified coordinates * <p> - * This method is analogous to {@link #unloadChunk(int, int, boolean, boolean)} where safe and saveis true + * This method is analogous to {@link #unloadChunk(int, int, boolean, + * boolean)} where safe and saveis true * * @param chunk the chunk to unload * @return true if the chunk has unloaded successfully, otherwise false @@ -199,7 +209,8 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Safely unloads and saves the {@link Chunk} at the specified coordinates * <p> - * This method is analogous to {@link #unloadChunk(int, int, boolean, boolean)} where safe and saveis true + * This method is analogous to {@link #unloadChunk(int, int, boolean, + * boolean)} where safe and saveis true * * @param x X-coordinate of the chunk * @param z Z-coordinate of the chunk @@ -208,9 +219,11 @@ public interface World extends PluginMessageRecipient, Metadatable { public boolean unloadChunk(int x, int z); /** - * Safely unloads and optionally saves the {@link Chunk} at the specified coordinates + * Safely unloads and optionally saves the {@link Chunk} at the specified + * coordinates * <p> - * This method is analogous to {@link #unloadChunk(int, int, boolean, boolean)} where save is true + * This method is analogous to {@link #unloadChunk(int, int, boolean, + * boolean)} where save is true * * @param x X-coordinate of the chunk * @param z Z-coordinate of the chunk @@ -220,20 +233,24 @@ public interface World extends PluginMessageRecipient, Metadatable { public boolean unloadChunk(int x, int z, boolean save); /** - * Unloads and optionally saves the {@link Chunk} at the specified coordinates + * Unloads and optionally saves the {@link Chunk} at the specified + * coordinates * * @param x X-coordinate of the chunk * @param z Z-coordinate of 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 */ public boolean unloadChunk(int x, int z, boolean save, boolean safe); /** - * Safely queues the {@link Chunk} at the specified coordinates for unloading + * Safely queues the {@link Chunk} at the specified coordinates for + * unloading * <p> - * This method is analogous to {@link #unloadChunkRequest(int, int, boolean)} where safe is true + * This method is analogous to {@link #unloadChunkRequest(int, int, + * boolean)} where safe is true * * @param x X-coordinate of the chunk * @param z Z-coordinate of the chunk @@ -312,7 +329,8 @@ public interface World extends PluginMessageRecipient, Metadatable { * * @param loc Location to spawn the tree * @param type Type of the tree to create - * @param delegate A class to call for each block changed as a result of this method + * @param delegate A class to call for each block changed as a result of + * this method * @return true if the tree was created successfully, otherwise false */ public boolean generateTree(Location loc, TreeType type, BlockChangeDelegate delegate); @@ -331,8 +349,10 @@ public interface World extends PluginMessageRecipient, Metadatable { * * @param loc The location to spawn the creature * @param type The creature to spawn - * @return Resulting LivingEntity of this method, or null if it was unsuccessful - * @deprecated Has issues spawning non LivingEntities. Use {@link #spawnEntity(Location, EntityType) spawnEntity} instead. + * @return Resulting LivingEntity of this method, or null if it was + * unsuccessful + * @deprecated Has issues spawning non LivingEntities. Use {@link + * #spawnEntity(Location, EntityType) spawnEntity} instead. */ @Deprecated public LivingEntity spawnCreature(Location loc, EntityType type); @@ -342,7 +362,8 @@ public interface World extends PluginMessageRecipient, Metadatable { * * @param loc The location to spawn the creature * @param type The creature to spawn - * @return Resulting LivingEntity of this method, or null if it was unsuccessful + * @return Resulting LivingEntity of this method, or null if it was + * unsuccessful */ @Deprecated public LivingEntity spawnCreature(Location loc, CreatureType type); @@ -378,27 +399,33 @@ public interface World extends PluginMessageRecipient, Metadatable { public List<LivingEntity> getLivingEntities(); /** - * Get a collection of all entities in this World matching the given class/interface + * 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 + * @return A List of all Entities currently residing in this world that + * match the given class/interface */ @Deprecated public <T extends Entity> Collection<T> getEntitiesByClass(Class<T>... classes); /** - * Get a collection of all entities in this World matching the given class/interface + * 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 + * @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); /** - * Get a collection of all entities in this World matching any of the given classes/interfaces + * 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 + * @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); @@ -455,11 +482,12 @@ public interface World extends PluginMessageRecipient, Metadatable { * <p> * The relative time is analogous to hours * 1000 * <p> - * Note that setting the relative time below the current relative time will - * actually move the clock forward a day. If you require to rewind time, please - * see setFullTime + * Note that setting the relative time below the current relative time + * will actually move the clock forward a day. If you require to rewind + * time, please see {@link #setFullTime()} * - * @param time The new relative time to set the in-game time to (in hours*1000) + * @param time The new relative time to set the in-game time to (in + * hours*1000) * @see #setFullTime(long) Sets the absolute time of this world */ public void setTime(long time); @@ -552,8 +580,8 @@ public interface World extends PluginMessageRecipient, Metadatable { public boolean createExplosion(double x, double y, double z, float power); /** - * Creates explosion at given coordinates with given power and optionally setting - * blocks on fire. + * Creates explosion at given coordinates with given power and optionally + * setting blocks on fire. * * @param x X coordinate * @param y Y coordinate @@ -565,8 +593,8 @@ public interface World extends PluginMessageRecipient, Metadatable { public boolean createExplosion(double x, double y, double z, float power, boolean setFire); /** - * Creates explosion at given coordinates with given power and optionally setting - * blocks on fire or breaking blocks. + * Creates explosion at given coordinates with given power and optionally + * setting blocks on fire or breaking blocks. * * @param x X coordinate * @param y Y coordinate @@ -588,8 +616,8 @@ public interface World extends PluginMessageRecipient, Metadatable { public boolean createExplosion(Location loc, float power); /** - * Creates explosion at given coordinates with given power and optionally setting - * blocks on fire. + * Creates explosion at given coordinates with given power and optionally + * setting blocks on fire. * * @param loc Location to blow up * @param power The power of explosion, where 4F is TNT @@ -652,41 +680,48 @@ public interface World extends PluginMessageRecipient, Metadatable { * @param clazz the class of the {@link Entity} to spawn * @param <T> the class of the {@link Entity} to spawn * @return an instance of the spawned {@link Entity} - * @throws IllegalArgumentException if either parameter is null or the {@link Entity} requested cannot be spawned + * @throws IllegalArgumentException if either parameter is null or the + * {@link Entity} requested cannot be spawned */ public <T extends Entity> T spawn(Location location, Class<T> clazz) throws IllegalArgumentException; /** - * Spawn a {@link FallingBlock} entity at the given {@link Location} of the specified {@link Material}. - * The material dictates what is falling. When the FallingBlock hits the ground, it will place that block. + * Spawn a {@link FallingBlock} entity at the given {@link Location} of + * the specified {@link Material}. The material dictates what is falling. + * When the FallingBlock hits the ground, it will place that block. * <p> - * The Material must be a block type, check with {@link Material#isBlock() material.isBlock()}. - * The Material may not be air. + * The Material must be a block type, check with {@link Material#isBlock() + * material.isBlock()}. The Material may not be air. * * @param location The {@link Location} to spawn the FallingBlock * @param material The block {@link Material} type * @param data The block data * @return The spawned {@link FallingBlock} instance - * @throws IllegalArgumentException if {@link Location} or {@link Material} are null or {@link Material} is not a block + * @throws IllegalArgumentException if {@link Location} or {@link + * Material} are null or {@link Material} is not a block */ public FallingBlock spawnFallingBlock(Location location, Material material, byte data) throws IllegalArgumentException; /** - * Spawn a {@link FallingBlock} entity at the given {@link Location} of the specified blockId (converted to {@link Material}) + * Spawn a {@link FallingBlock} entity at the given {@link Location} of + * the specified blockId (converted to {@link Material}) * * @param location The {@link Location} to spawn the FallingBlock * @param blockId The id of the intended material * @param blockData The block data * @return The spawned FallingBlock instance - * @throws IllegalArgumentException if location is null, or blockId is invalid + * @throws IllegalArgumentException if location is null, or blockId is + * invalid * @see #spawnFallingBlock(org.bukkit.Location, org.bukkit.Material, byte) */ public FallingBlock spawnFallingBlock(Location location, int blockId, byte blockData) throws IllegalArgumentException; /** - * Plays an effect to all players within a default radius around a given location. + * Plays an effect to all players within a default radius around a given + * location. * - * @param location the {@link Location} around which players must be to hear the sound + * @param location the {@link Location} around which players must be to + * hear the sound * @param effect the {@link Effect} * @param data a data bit needed for some effects */ @@ -695,7 +730,8 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Plays an effect to all players within a given radius around a location. * - * @param location the {@link Location} around which players must be to hear the effect + * @param location the {@link Location} around which players must be to + * hear the effect * @param effect the {@link Effect} * @param data a data bit needed for some effects * @param radius the radius around the location @@ -703,9 +739,11 @@ public interface World extends PluginMessageRecipient, Metadatable { public void playEffect(Location location, Effect effect, int data, int radius); /** - * Plays an effect to all players within a default radius around a given location. + * Plays an effect to all players within a default radius around a given + * location. * - * @param location the {@link Location} around which players must be to hear the sound + * @param location the {@link Location} around which players must be to + * hear the sound * @param effect the {@link Effect} * @param data a data bit needed for some effects */ @@ -714,7 +752,8 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Plays an effect to all players within a given radius around a location. * - * @param location the {@link Location} around which players must be to hear the effect + * @param location the {@link Location} around which players must be to + * hear the effect * @param effect the {@link Effect} * @param data a data bit needed for some effects * @param radius the radius around the location @@ -722,13 +761,16 @@ public interface World extends PluginMessageRecipient, Metadatable { public <T> void playEffect(Location location, Effect effect, T data, int radius); /** - * Get empty chunk snapshot (equivalent to all air blocks), optionally including valid biome - * data. Used for representing an ungenerated chunk, or for fetching only biome data without loading a chunk. + * Get empty chunk snapshot (equivalent to all air blocks), optionally + * including valid biome data. Used for representing an ungenerated chunk, + * or for fetching only biome data without loading a chunk. * * @param x - chunk x coordinate * @param z - chunk z coordinate - * @param includeBiome - if true, snapshot includes per-coordinate biome type - * @param includeBiomeTempRain - if true, snapshot includes per-coordinate raw biome temperature and rainfall + * @param includeBiome - if true, snapshot includes per-coordinate biome + * type + * @param includeBiomeTempRain - if true, snapshot includes per-coordinate + * raw biome temperature and rainfall * @return The empty snapshot. */ public ChunkSnapshot getEmptyChunkSnapshot(int x, int z, boolean includeBiome, boolean includeBiomeTempRain); @@ -736,8 +778,10 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Sets the spawn flags for this. * - * @param allowMonsters - if true, monsters are allowed to spawn in this world. - * @param allowAnimals - if true, animals are allowed to spawn in this world. + * @param allowMonsters - if true, monsters are allowed to spawn in this + * world. + * @param allowAnimals - if true, animals are allowed to spawn in this + * world. */ public void setSpawnFlags(boolean allowMonsters, boolean allowAnimals); @@ -776,7 +820,8 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Gets the temperature for the given block coordinates. * <p> - * It is safe to run this method when the block does not exist, it will not create the block. + * It is safe to run this method when the block does not exist, it will + * not create the block. * * @param x X coordinate of the block * @param z Z coordinate of the block @@ -787,7 +832,8 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Gets the humidity for the given block coordinates. * <p> - * It is safe to run this method when the block does not exist, it will not create the block. + * It is safe to run this method when the block does not exist, it will + * not create the block. * * @param x X coordinate of the block * @param z Z coordinate of the block @@ -814,16 +860,19 @@ public interface World extends PluginMessageRecipient, Metadatable { public int getSeaLevel(); /** - * Gets whether the world's spawn area should be kept loaded into memory or not. + * Gets whether the world's spawn area should be kept loaded into memory + * or not. * * @return true if the world's spawn area will be kept loaded into memory. */ public boolean getKeepSpawnInMemory(); /** - * Sets whether the world's spawn area should be kept loaded into memory or not. + * Sets whether the world's spawn area should be kept loaded into memory + * or not. * - * @param keepLoaded if true then the world's spawn area will be kept loaded into memory. + * @param keepLoaded if true then the world's spawn area will be kept + * loaded into memory. */ public void setKeepSpawnInMemory(boolean keepLoaded); @@ -837,7 +886,8 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Sets whether or not the world will automatically save * - * @param value true if the world should automatically save, otherwise false + * @param value true if the world should automatically save, otherwise + * false */ public void setAutoSave(boolean value); @@ -879,17 +929,22 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Gets the world's ticks per animal spawns value * <p> - * This value determines how many ticks there are between attempts to spawn animals. + * This value determines how many ticks there are between attempts to + * spawn animals. * <p> * <b>Example Usage:</b> * <ul> - * <li>A value of 1 will mean the server will attempt to spawn animals in this world every tick. - * <li>A value of 400 will mean the server will attempt to spawn animals in this world every 400th tick. + * <li>A value of 1 will mean the server will attempt to spawn animals in + * this world every tick. + * <li>A value of 400 will mean the server will attempt to spawn animals + * in this world every 400th tick. * <li>A value below 0 will be reset back to Minecraft's default. * </ul> * <p> * <b>Note:</b> - * If set to 0, animal spawning will be disabled for this world. We recommend using {@link #setSpawnFlags(boolean, boolean)} to control this instead. + * If set to 0, animal spawning will be disabled for this world. We + * recommend using {@link #setSpawnFlags(boolean, boolean)} to control + * this instead. * <p> * Minecraft default: 400. * @@ -900,38 +955,49 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Sets the world's ticks per animal spawns value * <p> - * This value determines how many ticks there are between attempts to spawn animals. + * This value determines how many ticks there are between attempts to + * spawn animals. * <p> * <b>Example Usage:</b> * <ul> - * <li>A value of 1 will mean the server will attempt to spawn animals in this world every tick. - * <li>A value of 400 will mean the server will attempt to spawn animals in this world every 400th tick. + * <li>A value of 1 will mean the server will attempt to spawn animals in + * this world every tick. + * <li>A value of 400 will mean the server will attempt to spawn animals + * in this world every 400th tick. * <li>A value below 0 will be reset back to Minecraft's default. * </ul> * <p> * <b>Note:</b> - * If set to 0, animal spawning will be disabled for this world. We recommend using {@link #setSpawnFlags(boolean, boolean)} to control this instead. + * If set to 0, animal spawning will be disabled for this world. We + * recommend using {@link #setSpawnFlags(boolean, boolean)} to control + * this instead. * <p> * Minecraft default: 400. * - * @param ticksPerAnimalSpawns the ticks per animal spawns value you want to set the world to + * @param ticksPerAnimalSpawns the ticks per animal spawns value you want + * to set the world to */ public void setTicksPerAnimalSpawns(int ticksPerAnimalSpawns); /** * Gets the world's ticks per monster spawns value * <p> - * This value determines how many ticks there are between attempts to spawn monsters. + * This value determines how many ticks there are between attempts to + * spawn monsters. * <p> * <b>Example Usage:</b> * <ul> - * <li>A value of 1 will mean the server will attempt to spawn monsters in this world every tick. - * <li>A value of 400 will mean the server will attempt to spawn monsters in this world every 400th tick. + * <li>A value of 1 will mean the server will attempt to spawn monsters in + * this world every tick. + * <li>A value of 400 will mean the server will attempt to spawn monsters + * in this world every 400th tick. * <li>A value below 0 will be reset back to Minecraft's default. * </ul> * <p> * <b>Note:</b> - * If set to 0, monsters spawning will be disabled for this world. We recommend using {@link #setSpawnFlags(boolean, boolean)} to control this instead. + * If set to 0, monsters spawning will be disabled for this world. We + * recommend using {@link #setSpawnFlags(boolean, boolean)} to control + * this instead. * <p> * Minecraft default: 1. * @@ -942,80 +1008,95 @@ public interface World extends PluginMessageRecipient, Metadatable { /** * Sets the world's ticks per monster spawns value * <p> - * This value determines how many ticks there are between attempts to spawn monsters. + * This value determines how many ticks there are between attempts to + * spawn monsters. * <p> * <b>Example Usage:</b> * <ul> - * <li>A value of 1 will mean the server will attempt to spawn monsters in this world on every tick. - * <li>A value of 400 will mean the server will attempt to spawn monsters in this world every 400th tick. + * <li>A value of 1 will mean the server will attempt to spawn monsters in + * this world on every tick. + * <li>A value of 400 will mean the server will attempt to spawn monsters + * in this world every 400th tick. * <li>A value below 0 will be reset back to Minecraft's default. * </ul> * <p> * <b>Note:</b> - * If set to 0, monsters spawning will be disabled for this world. We recommend using {@link #setSpawnFlags(boolean, boolean)} to control this instead. + * If set to 0, monsters spawning will be disabled for this world. We + * recommend using {@link #setSpawnFlags(boolean, boolean)} to control + * this instead. * <p> * Minecraft default: 1. * - * @param ticksPerMonsterSpawns the ticks per monster spawns value you want to set the world to + * @param ticksPerMonsterSpawns the ticks per monster spawns value you + * want to set the world to */ public void setTicksPerMonsterSpawns(int ticksPerMonsterSpawns); /** - * Gets limit for number of monsters that can spawn in a chunk in this world + * Gets limit for number of monsters that can spawn in a chunk in this + * world + * * @return The monster spawn limit */ int getMonsterSpawnLimit(); /** - * Sets the limit for number of monsters that can spawn in a chunk in this world + * Sets the limit for number of monsters that can spawn in a chunk in this + * world * <p> - * <b>Note:</b> - * If set to a negative number the world will use the server-wide spawn limit instead. + * <b>Note:</b> If set to a negative number the world will use the + * server-wide spawn limit instead. */ void setMonsterSpawnLimit(int limit); /** - * Gets the limit for number of animals that can spawn in a chunk in this world + * Gets the limit for number of animals that can spawn in a chunk in this + * world * * @return The animal spawn limit */ int getAnimalSpawnLimit(); /** - * Sets the limit for number of animals that can spawn in a chunk in this world + * Sets the limit for number of animals that can spawn in a chunk in this + * world * <p> - * <b>Note:</b> - * If set to a negative number the world will use the server-wide spawn limit instead. + * <b>Note:</b> If set to a negative number the world will use the + * server-wide spawn limit instead. */ void setAnimalSpawnLimit(int limit); /** - * Gets the limit for number of water animals that can spawn in a chunk in this world + * Gets the limit for number of water animals that can spawn in a chunk in + * this world * * @return The water animal spawn limit */ int getWaterAnimalSpawnLimit(); /** - * Sets the limit for number of water animals that can spawn in a chunk in this world + * Sets the limit for number of water animals that can spawn in a chunk in + * this world * <p> - * <b>Note:</b> - * If set to a negative number the world will use the server-wide spawn limit instead. + * <b>Note:</b> If set to a negative number the world will use the + * server-wide spawn limit instead. */ void setWaterAnimalSpawnLimit(int limit); /** - * Gets the limit for number of ambient mobs that can spawn in a chunk in this world + * Gets the limit for number of ambient mobs that can spawn in a chunk in + * this world * * @return The ambient spawn limit */ int getAmbientSpawnLimit(); /** - * Sets the limit for number of ambient mobs that can spawn in a chunk in this world + * Sets the limit for number of ambient mobs that can spawn in a chunk in + * this world * <p> - * <b>Note:</b> - * If set to a negative number the world will use the server-wide spawn limit instead. + * <b>Note:</b> If set to a negative number the world will use the + * server-wide spawn limit instead. */ void setAmbientSpawnLimit(int limit); @@ -1074,6 +1155,7 @@ public interface World extends PluginMessageRecipient, Metadatable { * Represents various map environment types that a world may be */ public enum Environment { + /** * Represents the "normal"/"surface world" map */ diff --git a/src/main/java/org/bukkit/WorldCreator.java b/src/main/java/org/bukkit/WorldCreator.java index 8bfbb262..9a5afd2d 100644 --- a/src/main/java/org/bukkit/WorldCreator.java +++ b/src/main/java/org/bukkit/WorldCreator.java @@ -141,8 +141,8 @@ public class WorldCreator { /** * Gets the generator that will be used to create or load the world. * <p> - * This may be null, in which case the "natural" generator for this environment - * will be used. + * This may be null, in which case the "natural" generator for this + * environment will be used. * * @return Chunk generator */ @@ -153,8 +153,8 @@ public class WorldCreator { /** * Sets the generator that will be used to create or load the world. * <p> - * This may be null, in which case the "natural" generator for this environment - * will be used. + * This may be null, in which case the "natural" generator for this + * environment will be used. * * @param generator Chunk generator * @return This object, for chaining @@ -168,11 +168,12 @@ public class WorldCreator { /** * Sets the generator that will be used to create or load the world. * <p> - * This may be null, in which case the "natural" generator for this environment - * will be used. + * This may be null, in which case the "natural" generator for this + * environment will be used. * <p> - * If the generator cannot be found for the given name, the natural environment generator - * will be used instead and a warning will be printed to the console. + * If the generator cannot be found for the given name, the natural + * environment generator will be used instead and a warning will be + * printed to the console. * * @param generator Name of the generator to use, in "plugin:id" notation * @return This object, for chaining @@ -186,14 +187,16 @@ public class WorldCreator { /** * Sets the generator that will be used to create or load the world. * <p> - * This may be null, in which case the "natural" generator for this environment - * will be used. + * This may be null, in which case the "natural" generator for this + * environment will be used. * <p> - * If the generator cannot be found for the given name, the natural environment generator - * will be used instead and a warning will be printed to the specified output + * If the generator cannot be found for the given name, the natural + * environment generator will be used instead and a warning will be + * printed to the specified output * * @param generator Name of the generator to use, in "plugin:id" notation - * @param output {@link CommandSender} that will receive any error messages + * @param output {@link CommandSender} that will receive any error + * messages * @return This object, for chaining */ public WorldCreator generator(String generator, CommandSender output) { @@ -203,7 +206,8 @@ public class WorldCreator { } /** - * Sets whether or not worlds created or loaded with this creator will have structures. + * 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 @@ -226,8 +230,8 @@ public class WorldCreator { /** * Creates a world with the specified options. * <p> - * If the world already exists, it will be loaded from disk and some options - * may be ignored. + * If the world already exists, it will be loaded from disk and some + * options may be ignored. * * @return Newly created or loaded world */ @@ -248,12 +252,13 @@ public class WorldCreator { /** * Attempts to get the {@link ChunkGenerator} with the given name. * <p> - * If the generator is not found, null will be returned and a message will be - * printed to the specified {@link CommandSender} explaining why. + * If the generator is not found, null will be returned and a message will + * be printed to the specified {@link CommandSender} explaining why. * <p> - * The name must be in the "plugin:id" notation, or optionally just "plugin", - * where "plugin" is the safe-name of a plugin and "id" is an optional unique - * identifier for the generator you wish to request from the plugin. + * The name must be in the "plugin:id" notation, or optionally just + * "plugin", where "plugin" is the safe-name of a plugin and "id" is an + * optional unique identifier for the generator you wish to request from + * the plugin. * * @param world Name of the world this will be used for * @param name Name of the generator to retrieve diff --git a/src/main/java/org/bukkit/block/Block.java b/src/main/java/org/bukkit/block/Block.java index 47a69d22..4a53109a 100644 --- a/src/main/java/org/bukkit/block/Block.java +++ b/src/main/java/org/bukkit/block/Block.java @@ -11,9 +11,9 @@ import org.bukkit.metadata.Metadatable; /** * Represents a block. This is a live object, and only one Block may exist for - * any given location in a world. The state of the block may change concurrently - * to your own handling of it; use block.getState() to get a snapshot state of a - * block which will not be modified. + * any given location in a world. The state of the block may change + * concurrently to your own handling of it; use block.getState() to get a + * snapshot state of a block which will not be modified. */ public interface Block extends Metadatable { @@ -50,8 +50,8 @@ public interface Block extends Metadatable { /** * Gets the block at the given distance of the given face * <p> - * For example, the following method places water at 100,102,100; two blocks - * above 100,100,100. + * For example, the following method places water at 100,102,100; two + * blocks above 100,100,100. * * <pre> * Block block = world.getBlockAt(100, 100, 100); @@ -91,7 +91,8 @@ public interface Block extends Metadatable { /** * Get the amount of light at this block from the sky. * <p> - * Any light given from other sources (such as blocks like torches) will be ignored. + * Any light given from other sources (such as blocks like torches) will + * be ignored. * * @return Sky light level */ @@ -142,8 +143,10 @@ public interface Block extends Metadatable { Location getLocation(); /** - * Stores the location of the block in the provided Location object.<br /> - * If the provided Location is null this method does nothing and returns null. + * Stores the location of the block in the provided Location object. + * <p> + * If the provided Location is null this method does nothing and returns + * null. * * @return The Location object provided or null */ @@ -237,8 +240,8 @@ public interface Block extends Metadatable { * Captures the current state of this block. You may then cast that state * into any accepted type, such as Furnace or Sign. * <p> - * The returned object will never be updated, and you are not guaranteed that - * (for example) a sign is still a sign after you capture its state. + * The returned object will never be updated, and you are not guaranteed + * that (for example) a sign is still a sign after you capture its state. * * @return BlockState with the current state of this block. */ @@ -291,7 +294,8 @@ public interface Block extends Metadatable { /** * Returns the redstone power being provided to this block face * - * @param face the face of the block to query or BlockFace.SELF for the block itself + * @param face the face of the block to query or BlockFace.SELF for the + * block itself * @return The power level. */ int getBlockPower(BlockFace face); @@ -306,7 +310,8 @@ public interface Block extends Metadatable { /** * Checks if this block is empty. * <p> - * A block is considered empty when {@link #getType()} returns {@link Material#AIR}. + * A block is considered empty when {@link #getType()} returns {@link + * Material#AIR}. * * @return true if this block is empty */ @@ -315,7 +320,9 @@ public interface Block extends Metadatable { /** * Checks if this block is liquid. * <p> - * A block is considered liquid when {@link #getType()} returns {@link Material#WATER}, {@link Material#STATIONARY_WATER}, {@link Material#LAVA} or {@link Material#STATIONARY_LAVA}. + * A block is considered liquid when {@link #getType()} returns {@link + * Material#WATER}, {@link Material#STATIONARY_WATER}, {@link + * Material#LAVA} or {@link Material#STATIONARY_LAVA}. * * @return true if this block is liquid */ @@ -350,7 +357,8 @@ public interface Block extends Metadatable { boolean breakNaturally(); /** - * Breaks the block and spawns items as if a player had digged it with a specific tool + * Breaks the block and spawns items as if a player had digged it with a + * specific tool * * @param tool The tool or item in hand used for digging * @return true if the block was destroyed @@ -365,7 +373,8 @@ public interface Block extends Metadatable { Collection<ItemStack> getDrops(); /** - * Returns a list of items which would drop by destroying this block with a specific tool + * Returns a list of items which would drop by destroying this block with + * a specific tool * * @param tool The tool or item in hand used for digging * @return a list of dropped items for this type of block diff --git a/src/main/java/org/bukkit/block/BlockState.java b/src/main/java/org/bukkit/block/BlockState.java index 784454a4..ca571739 100644 --- a/src/main/java/org/bukkit/block/BlockState.java +++ b/src/main/java/org/bukkit/block/BlockState.java @@ -8,12 +8,13 @@ import org.bukkit.material.MaterialData; import org.bukkit.metadata.Metadatable; /** - * Represents a captured state of a block, which will not change automatically. + * Represents a captured state of a block, which will not change + * automatically. * <p> - * Unlike Block, which only one object can exist per coordinate, BlockState can - * exist multiple times for any given Block. Note that another plugin may change - * the state of the block and you will not know, or they may change the block to - * another type entirely, causing your BlockState to become invalid. + * Unlike Block, which only one object can exist per coordinate, BlockState + * can exist multiple times for any given Block. Note that another plugin may + * change the state of the block and you will not know, or they may change the + * block to another type entirely, causing your BlockState to become invalid. */ public interface BlockState extends Metadatable { @@ -90,8 +91,10 @@ public interface BlockState extends Metadatable { Location getLocation(); /** - * Stores the location of this block in the provided Location object.<br /> - * If the provided Location is null this method does nothing and returns null. + * Stores the location of this block in the provided Location object. + * <p> + * If the provided Location is null this method does nothing and returns + * null. * * @return The Location object provided or null */ @@ -129,8 +132,8 @@ public interface BlockState extends Metadatable { boolean setTypeId(int type); /** - * Attempts to update the block represented by this state, setting it to the - * new values as defined by this state. + * Attempts to update the block represented by this state, setting it to + * the new values as defined by this state. * <p> * This has the same effect as calling update(false). That is to say, * this will not modify the state of a block if it is no longer the same @@ -143,11 +146,11 @@ public interface BlockState extends Metadatable { boolean update(); /** - * Attempts to update the block represented by this state, setting it to the - * new values as defined by this state. + * Attempts to update the block represented by this state, setting it to + * the new values as defined by this state. * <p> - * This has the same effect as calling update(force, true). That is to say, - * this will trigger a physics update to surrounding blocks. + * This has the same effect as calling update(force, true). That is to + * say, this will trigger a physics update to surrounding blocks. * * @param force true to forcefully set the state * @return true if the update was successful, otherwise false @@ -155,21 +158,22 @@ public interface BlockState extends Metadatable { boolean update(boolean force); /** - * Attempts to update the block represented by this state, setting it to the - * new values as defined by this state. + * Attempts to update the block represented by this state, setting it to + * the new values as defined by this state. * <p> - * Unless force is true, this will not modify the state of a block if it is - * no longer the same type as it was when this state was taken. It will return - * false in this eventuality. + * Unless force is true, this will not modify the state of a block if it + * is no longer the same type as it was when this state was taken. It will + * return false in this eventuality. * <p> - * If force is true, it will set the type of the block to match the new state, - * set the state data and then return true. + * If force is true, it will set the type of the block to match the new + * state, set the state data and then return true. * <p> - * If applyPhysics is true, it will trigger a physics update on surrounding - * blocks which could cause them to update or disappear. + * If applyPhysics is true, it will trigger a physics update on + * surrounding blocks which could cause them to update or disappear. * * @param force true to forcefully set the state - * @param applyPhysics false to cancel updating physics on surrounding blocks + * @param applyPhysics false to cancel updating physics on surrounding + * blocks * @return true if the update was successful, otherwise false */ boolean update(boolean force, boolean applyPhysics); diff --git a/src/main/java/org/bukkit/block/Chest.java b/src/main/java/org/bukkit/block/Chest.java index 8f6e961b..125d5e70 100644 --- a/src/main/java/org/bukkit/block/Chest.java +++ b/src/main/java/org/bukkit/block/Chest.java @@ -8,8 +8,8 @@ import org.bukkit.inventory.Inventory; public interface Chest extends BlockState, ContainerBlock { /** - * Returns the chest's inventory. If this is a double chest, it returns just - * the portion of the inventory linked to this half of the chest. + * Returns the chest's inventory. If this is a double chest, it returns + * just the portion of the inventory linked to this half of the chest. * * @return The inventory. */ diff --git a/src/main/java/org/bukkit/block/ContainerBlock.java b/src/main/java/org/bukkit/block/ContainerBlock.java index f51d0fa8..c69ac9e5 100644 --- a/src/main/java/org/bukkit/block/ContainerBlock.java +++ b/src/main/java/org/bukkit/block/ContainerBlock.java @@ -4,6 +4,7 @@ import org.bukkit.inventory.InventoryHolder; /** * Indicates a block type that has inventory. + * * @deprecated in favour of {@link InventoryHolder} */ @Deprecated diff --git a/src/main/java/org/bukkit/block/DoubleChest.java b/src/main/java/org/bukkit/block/DoubleChest.java index cfc5b208..148099c5 100644 --- a/src/main/java/org/bukkit/block/DoubleChest.java +++ b/src/main/java/org/bukkit/block/DoubleChest.java @@ -6,6 +6,9 @@ import org.bukkit.inventory.DoubleChestInventory; import org.bukkit.inventory.Inventory; import org.bukkit.inventory.InventoryHolder; +/** + * Represents a double chest. + */ public class DoubleChest implements InventoryHolder { private DoubleChestInventory inventory; diff --git a/src/main/java/org/bukkit/block/PistonMoveReaction.java b/src/main/java/org/bukkit/block/PistonMoveReaction.java index 02d9649e..e5279f7e 100644 --- a/src/main/java/org/bukkit/block/PistonMoveReaction.java +++ b/src/main/java/org/bukkit/block/PistonMoveReaction.java @@ -4,6 +4,7 @@ import java.util.HashMap; import java.util.Map; public enum PistonMoveReaction { + /** * Indicates that the block can be pushed or pulled. */ diff --git a/src/main/java/org/bukkit/command/Command.java b/src/main/java/org/bukkit/command/Command.java index 4ad60996..1c235720 100644 --- a/src/main/java/org/bukkit/command/Command.java +++ b/src/main/java/org/bukkit/command/Command.java @@ -64,13 +64,14 @@ public abstract class Command { } /** - * Executed on tab completion for this command, returning a list of options - * the player can tab through. + * Executed on tab completion for this command, returning a list of + * options the player can tab through. * * @param sender Source object which is executing this command * @param alias the alias being used * @param args All arguments passed to the command, split via ' ' - * @return a list of tab-completions for the specified arguments. This will never be null. List may be immutable. + * @return a list of tab-completions for the specified arguments. This + * will never be null. List may be immutable. * @throws IllegalArgumentException if sender, alias, or args is null */ public List<String> tabComplete(CommandSender sender, String alias, String[] args) throws IllegalArgumentException { @@ -108,7 +109,8 @@ public abstract class Command { } /** - * Gets the permission required by users to be able to perform this command + * Gets the permission required by users to be able to perform this + * command * * @return Permission name, or null if none */ @@ -117,7 +119,8 @@ public abstract class Command { } /** - * Sets the permission required by users to be able to perform this command + * Sets the permission required by users to be able to perform this + * command * * @param permission Permission name or null */ @@ -126,9 +129,11 @@ public abstract class Command { } /** - * Tests the given {@link CommandSender} to see if they can perform this command. + * Tests the given {@link CommandSender} to see if they can perform this + * command. * <p> - * If they do not have permission, they will be informed that they cannot do this. + * If they do not have permission, they will be informed that they cannot + * do this. * * @param target User to test * @return true if they can use it, otherwise false @@ -150,7 +155,8 @@ public abstract class Command { } /** - * Tests the given {@link CommandSender} to see if they can perform this command. + * Tests the given {@link CommandSender} to see if they can perform this + * command. * <p> * No error is sent to the sender. * @@ -181,12 +187,14 @@ public abstract class Command { } /** - * Sets the label of this command - * If the command is currently registered the label change will only take effect after - * its been reregistered e.g. after a /reload + * Sets the label of this command. + * <p> + * If the command is currently registered the label change will only take + * effect after its been re-registered e.g. after a /reload * * @param name The command's name - * @return returns true if the name change happened instantly or false if it was scheduled for reregistration + * @return returns true if the name change happened instantly or false if + * it was scheduled for re-registration */ public boolean setLabel(String name) { this.nextLabel = name; @@ -198,11 +206,12 @@ public abstract class Command { } /** - * Registers this command to a CommandMap + * Registers this command to a CommandMap. * Once called it only allows changes the registered CommandMap * * @param commandMap the CommandMap to register this command to - * @return true if the registration was successful (the current registered CommandMap was the passed CommandMap or null) false otherwise + * @return true if the registration was successful (the current registered + * CommandMap was the passed CommandMap or null) false otherwise */ public boolean register(CommandMap commandMap) { if (allowChangesFrom(commandMap)) { @@ -214,10 +223,13 @@ public abstract class Command { } /** - * Unregisters this command from the passed CommandMap applying any outstanding changes + * Unregisters this command from the passed CommandMap applying any + * outstanding changes * * @param commandMap the CommandMap to unregister - * @return true if the unregistration was successfull (the current registered CommandMap was the passed CommandMap or null) false otherwise + * @return true if the unregistration was successfull (the current + * registered CommandMap was the passed CommandMap or null) false + * otherwise */ public boolean unregister(CommandMap commandMap) { if (allowChangesFrom(commandMap)) { @@ -253,7 +265,8 @@ public abstract class Command { } /** - * Returns a message to be displayed on a failed permission check for this command + * Returns a message to be displayed on a failed permission check for this + * command * * @return Permission check failed message */ diff --git a/src/main/java/org/bukkit/command/CommandException.java b/src/main/java/org/bukkit/command/CommandException.java index 76c1a016..b63015f4 100644 --- a/src/main/java/org/bukkit/command/CommandException.java +++ b/src/main/java/org/bukkit/command/CommandException.java @@ -7,12 +7,14 @@ package org.bukkit.command; public class CommandException extends RuntimeException { /** - * Creates a new instance of <code>CommandException</code> without detail message. + * Creates a new instance of <code>CommandException</code> without detail + * message. */ public CommandException() {} /** - * Constructs an instance of <code>CommandException</code> with the specified detail message. + * Constructs an instance of <code>CommandException</code> with the + * specified detail message. * * @param msg the detail message. */ diff --git a/src/main/java/org/bukkit/command/CommandMap.java b/src/main/java/org/bukkit/command/CommandMap.java index e7fad287..e7e20d89 100644 --- a/src/main/java/org/bukkit/command/CommandMap.java +++ b/src/main/java/org/bukkit/command/CommandMap.java @@ -6,37 +6,62 @@ public interface CommandMap { /** * Registers all the commands belonging to a certain plugin. + * <p> * Caller can use:- - * command.getName() to determine the label registered for this command - * command.getAliases() to determine the aliases which where registered + * <ul> + * <li>command.getName() to determine the label registered for this + * command + * <li>command.getAliases() to determine the aliases which where + * registered + * </ul> * - * @param fallbackPrefix a prefix which is prepended to each command with a ':' one or more times to make the command unique + * @param fallbackPrefix a prefix which is prepended to each command with + * a ':' one or more times to make the command unique * @param commands a list of commands to register */ public void registerAll(String fallbackPrefix, List<Command> commands); /** - * Registers a command. Returns true on success; false if name is already taken and fallback had to be used. + * Registers a command. Returns true on success; false if name is already + * taken and fallback had to be used. + * <p> * Caller can use:- - * command.getName() to determine the label registered for this command - * command.getAliases() to determine the aliases which where registered + * <ul> + * <li>command.getName() to determine the label registered for this + * command + * <li>command.getAliases() to determine the aliases which where + * registered + * </ul> * * @param label the label of the command, without the '/'-prefix. - * @param fallbackPrefix a prefix which is prepended to the command with a ':' one or more times to make the command unique + * @param fallbackPrefix a prefix which is prepended to the command with a + * ':' one or more times to make the command unique * @param command the command to register - * @return true if command was registered with the passed in label, false otherwise, which indicates the fallbackPrefix was used one or more times + * @return true if command was registered with the passed in label, false + * otherwise, which indicates the fallbackPrefix was used one or more + * times */ public boolean register(String label, String fallbackPrefix, Command command); /** - * Registers a command. Returns true on success; false if name is already taken and fallback had to be used. + * Registers a command. Returns true on success; false if name is already + * taken and fallback had to be used. + * <p> * Caller can use:- - * command.getName() to determine the label registered for this command - * command.getAliases() to determine the aliases which where registered + * <ul> + * <li>command.getName() to determine the label registered for this + * command + * <li>command.getAliases() to determine the aliases which where + * registered + * </ul> * - * @param fallbackPrefix a prefix which is prepended to the command with a ':' one or more times to make the command unique - * @param command the command to register, from which label is determined from the command name - * @return true if command was registered with the passed in label, false otherwise, which indicates the fallbackPrefix was used one or more times + * @param fallbackPrefix a prefix which is prepended to the command with a + * ':' one or more times to make the command unique + * @param command the command to register, from which label is determined + * from the command name + * @return true if command was registered with the passed in label, false + * otherwise, which indicates the fallbackPrefix was used one or more + * times */ public boolean register(String fallbackPrefix, Command command); @@ -46,7 +71,8 @@ public interface CommandMap { * @param sender The command's sender * @param cmdLine command + arguments. Example: "/test abc 123" * @return returns false if no target is found, true otherwise. - * @throws CommandException Thrown when the executor for the given command fails with an unhandled exception + * @throws CommandException Thrown when the executor for the given command + * fails with an unhandled exception */ public boolean dispatch(CommandSender sender, String cmdLine) throws CommandException; @@ -59,18 +85,24 @@ public interface CommandMap { * Gets the command registered to the specified name * * @param name Name of the command to retrieve - * @return Command with the specified name or null if a command with that label doesn't exist + * @return Command with the specified name or null if a command with that + * label doesn't exist */ public Command getCommand(String name); /** - * Looks for the requested command and executes an appropriate tab-completer if found. This method will also tab-complete partial commands. + * Looks for the requested command and executes an appropriate + * tab-completer if found. This method will also tab-complete partial + * commands. * * @param sender The command's sender. - * @param cmdLine The entire command string to tab-complete, excluding initial slash. - * @return a list of possible tab-completions. This list may be immutable. Will be null if no matching command of which sender has permission. - * @throws CommandException Thrown when the tab-completer for the given command fails with an unhandled exception + * @param cmdLine The entire command string to tab-complete, excluding + * initial slash. + * @return a list of possible tab-completions. This list may be immutable. + * Will be null if no matching command of which sender has permission. + * @throws CommandException Thrown when the tab-completer for the given + * command fails with an unhandled exception * @throws IllegalArgumentException if either sender or cmdLine are null */ public List<String> tabComplete(CommandSender sender, String cmdLine) throws IllegalArgumentException; diff --git a/src/main/java/org/bukkit/command/PluginCommand.java b/src/main/java/org/bukkit/command/PluginCommand.java index f90ee7e0..3bfa31fc 100644 --- a/src/main/java/org/bukkit/command/PluginCommand.java +++ b/src/main/java/org/bukkit/command/PluginCommand.java @@ -104,17 +104,20 @@ public final class PluginCommand extends Command implements PluginIdentifiableCo } /** - * {@inheritDoc}<br> - * <br> - * Delegates to the tab completer if present.<br> - * If it is not present or returns null, will delegate to the current command - * executor if it implements {@link TabCompleter}. If a non-null list has not - * been found, will default to standard player name completion in - * {@link Command#tabComplete(CommandSender, String, String[])}.<br> - * <br> + * {@inheritDoc} + * <p> + * Delegates to the tab completer if present. + * <p> + * If it is not present or returns null, will delegate to the current + * command executor if it implements {@link TabCompleter}. If a non-null + * list has not been found, will default to standard player name + * completion in {@link + * Command#tabComplete(CommandSender, String, String[])}. + * <p> * This method does not consider permissions. * - * @throws CommandException if the completer or executor throw an exception during the process of tab-completing. + * @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 */ @Override diff --git a/src/main/java/org/bukkit/command/PluginIdentifiableCommand.java b/src/main/java/org/bukkit/command/PluginIdentifiableCommand.java index c58abb66..c5e0d2c4 100644 --- a/src/main/java/org/bukkit/command/PluginIdentifiableCommand.java +++ b/src/main/java/org/bukkit/command/PluginIdentifiableCommand.java @@ -3,12 +3,13 @@ package org.bukkit.command; import org.bukkit.plugin.Plugin; /** - * This interface is used by the help system to group commands into sub-indexes based - * on the {@link Plugin} they are a part of. Custom command implementations will need to - * implement this interface to have a sub-index automatically generated on the plugin's - * behalf. + * This interface is used by the help system to group commands into + * sub-indexes based on the {@link Plugin} they are a part of. Custom command + * implementations will need to implement this interface to have a sub-index + * automatically generated on the plugin's behalf. */ public interface PluginIdentifiableCommand { + /** * Gets the owner of this PluginIdentifiableCommand. * diff --git a/src/main/java/org/bukkit/command/SimpleCommandMap.java b/src/main/java/org/bukkit/command/SimpleCommandMap.java index f7167824..c2f488a7 100644 --- a/src/main/java/org/bukkit/command/SimpleCommandMap.java +++ b/src/main/java/org/bukkit/command/SimpleCommandMap.java @@ -117,14 +117,18 @@ public class SimpleCommandMap implements CommandMap { } /** - * Registers a command with the given name is possible, otherwise uses fallbackPrefix to create a unique name if its not an alias + * Registers a command with the given name is possible, otherwise uses + * fallbackPrefix to create a unique name if its not an alias * * @param label the name of the command, without the '/'-prefix. - * @param fallbackPrefix a prefix which is prepended to the command with a ':' one or more times to make the command unique + * @param fallbackPrefix a prefix which is prepended to the command with a + * ':' one or more times to make the command unique * @param command the command to register - * @return true if command was registered with the passed in label, false otherwise. - * If isAlias was true a return of false indicates no command was registerd - * If isAlias was false a return of false indicates the fallbackPrefix was used one or more times to create a unique name for the command + * @return true if command was registered with the passed in label, false + * otherwise. If isAlias was true a return of false indicates no + * command was registered. If isAlias was false a return of false + * indicates the fallbackPrefix was used one or more times to create a + * unique name for the command */ private synchronized boolean register(String label, String fallbackPrefix, Command command, boolean isAlias) { String lowerLabel = label.trim().toLowerCase(); diff --git a/src/main/java/org/bukkit/command/TabCommandExecutor.java b/src/main/java/org/bukkit/command/TabCommandExecutor.java index bf6ddd4e..d24d795c 100644 --- a/src/main/java/org/bukkit/command/TabCommandExecutor.java +++ b/src/main/java/org/bukkit/command/TabCommandExecutor.java @@ -5,7 +5,8 @@ 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 + * @deprecated Remains for plugins that would have implemented it even without + * functionality * @see TabExecutor */ @Deprecated diff --git a/src/main/java/org/bukkit/command/TabCompleter.java b/src/main/java/org/bukkit/command/TabCompleter.java index 3ba64fe8..6d61e3ab 100644 --- a/src/main/java/org/bukkit/command/TabCompleter.java +++ b/src/main/java/org/bukkit/command/TabCompleter.java @@ -13,8 +13,10 @@ public interface TabCompleter { * @param sender Source of the command * @param command Command which was executed * @param alias The alias used - * @param args The arguments passed to the command, including final partial argument to be completed and command label - * @return A List of possible completions for the final argument, or null to default to the command executor + * @param args The arguments passed to the command, including final + * partial argument to be completed and command label + * @return A List of possible completions for the final argument, or null + * to default to the command executor */ public List<String> onTabComplete(CommandSender sender, Command command, String alias, String[] args); } diff --git a/src/main/java/org/bukkit/command/TabExecutor.java b/src/main/java/org/bukkit/command/TabExecutor.java index 67b3503d..6b8e3fb2 100644 --- a/src/main/java/org/bukkit/command/TabExecutor.java +++ b/src/main/java/org/bukkit/command/TabExecutor.java @@ -1,7 +1,8 @@ package org.bukkit.command; /** - * This class is provided as a convenience to implement both TabCompleter and CommandExecutor. + * This class is provided as a convenience to implement both TabCompleter and + * CommandExecutor. */ public interface TabExecutor extends TabCompleter, CommandExecutor { } diff --git a/src/main/java/org/bukkit/configuration/Configuration.java b/src/main/java/org/bukkit/configuration/Configuration.java index 6fa80186..9289c218 100644 --- a/src/main/java/org/bukkit/configuration/Configuration.java +++ b/src/main/java/org/bukkit/configuration/Configuration.java @@ -9,11 +9,12 @@ public interface Configuration extends ConfigurationSection { /** * Sets the default value of the given path as provided. * <p> - * If no source {@link Configuration} was provided as a default collection, - * then a new {@link MemoryConfiguration} will be created to hold the new default - * value. + * If no source {@link Configuration} was provided as a default + * collection, then a new {@link MemoryConfiguration} will be created to + * hold the new default value. * <p> - * If value is null, the value will be removed from the default Configuration source. + * If value is null, the value will be removed from the default + * Configuration source. * * @param path Path of the value to set. * @param value Value to set the default to. @@ -24,9 +25,9 @@ public interface Configuration extends ConfigurationSection { /** * Sets the default values of the given paths as provided. * <p> - * If no source {@link Configuration} was provided as a default collection, - * then a new {@link MemoryConfiguration} will be created to hold the new default - * values. + * If no source {@link Configuration} was provided as a default + * collection, then a new {@link MemoryConfiguration} will be created to + * hold the new default values. * * @param defaults A map of Path->Values to add to defaults. * @throws IllegalArgumentException Thrown if defaults is null. @@ -36,13 +37,14 @@ public interface Configuration extends ConfigurationSection { /** * Sets the default values of the given paths as provided. * <p> - * If no source {@link Configuration} was provided as a default collection, - * then a new {@link MemoryConfiguration} will be created to hold the new default - * value. + * If no source {@link Configuration} was provided as a default + * collection, then a new {@link MemoryConfiguration} will be created to + * hold the new default value. * <p> - * This method will not hold a reference to the specified Configuration, nor will it - * automatically update if that Configuration ever changes. If you require this, - * you should set the default source with {@link #setDefaults(org.bukkit.configuration.Configuration)}. + * This method will not hold a reference to the specified Configuration, + * nor will it automatically update if that Configuration ever changes. If + * you require this, you should set the default source with {@link + * #setDefaults(org.bukkit.configuration.Configuration)}. * * @param defaults A configuration holding a list of defaults to copy. * @throws IllegalArgumentException Thrown if defaults is null or this. @@ -52,8 +54,8 @@ public interface Configuration extends ConfigurationSection { /** * Sets the source of all default values for this {@link Configuration}. * <p> - * If a previous source was set, or previous default values were defined, then they will - * not be copied to the new source. + * If a previous source was set, or previous default values were defined, + * then they will not be copied to the new source. * * @param defaults New source of default values for this configuration. * @throws IllegalArgumentException Thrown if defaults is null or this. @@ -63,9 +65,9 @@ public interface Configuration extends ConfigurationSection { /** * Gets the source {@link Configuration} for this configuration. * <p> - * If no configuration source was set, but default values were added, then a - * {@link MemoryConfiguration} will be returned. If no source was set and no - * defaults were set, then this method will return null. + * If no configuration source was set, but default values were added, then + * a {@link MemoryConfiguration} will be returned. If no source was set + * and no defaults were set, then this method will return null. * * @return Configuration source for default values, or null if none exist. */ diff --git a/src/main/java/org/bukkit/configuration/ConfigurationOptions.java b/src/main/java/org/bukkit/configuration/ConfigurationOptions.java index 73ca421c..2f593822 100644 --- a/src/main/java/org/bukkit/configuration/ConfigurationOptions.java +++ b/src/main/java/org/bukkit/configuration/ConfigurationOptions.java @@ -1,7 +1,8 @@ package org.bukkit.configuration; /** - * Various settings for controlling the input and output of a {@link Configuration} + * Various settings for controlling the input and output of a {@link + * Configuration} */ public class ConfigurationOptions { private char pathSeparator = '.'; @@ -22,10 +23,11 @@ public class ConfigurationOptions { } /** - * Gets the char that will be used to separate {@link ConfigurationSection}s + * Gets the char that will be used to separate {@link + * ConfigurationSection}s * <p> - * This value does not affect how the {@link Configuration} is stored, only in - * how you access the data. The default value is '.'. + * This value does not affect how the {@link Configuration} is stored, + * only in how you access the data. The default value is '.'. * * @return Path separator */ @@ -34,10 +36,11 @@ public class ConfigurationOptions { } /** - * Sets the char that will be used to separate {@link ConfigurationSection}s + * Sets the char that will be used to separate {@link + * ConfigurationSection}s * <p> - * This value does not affect how the {@link Configuration} is stored, only in - * how you access the data. The default value is '.'. + * This value does not affect how the {@link Configuration} is stored, + * only in how you access the data. The default value is '.'. * * @param value Path separator * @return This object, for chaining @@ -48,13 +51,16 @@ public class ConfigurationOptions { } /** - * Checks if the {@link Configuration} should copy values from its default {@link Configuration} directly. + * Checks if the {@link Configuration} should copy values from its default + * {@link Configuration} directly. * <p> - * If this is true, all values in the default Configuration will be directly copied, - * making it impossible to distinguish between values that were set and values that - * are provided by default. As a result, {@link ConfigurationSection#contains(java.lang.String)} will always - * return the same value as {@link ConfigurationSection#isSet(java.lang.String)}. - * The default value is false. + * If this is true, all values in the default Configuration will be + * directly copied, making it impossible to distinguish between values + * that were set and values that are provided by default. As a result, + * {@link ConfigurationSection#contains(java.lang.String)} will always + * return the same value as {@link + * ConfigurationSection#isSet(java.lang.String)}. The default value is + * false. * * @return Whether or not defaults are directly copied */ @@ -63,13 +69,16 @@ public class ConfigurationOptions { } /** - * Sets if the {@link Configuration} should copy values from its default {@link Configuration} directly. + * Sets if the {@link Configuration} should copy values from its default + * {@link Configuration} directly. * <p> - * If this is true, all values in the default Configuration will be directly copied, - * making it impossible to distinguish between values that were set and values that - * are provided by default. As a result, {@link ConfigurationSection#contains(java.lang.String)} will always - * return the same value as {@link ConfigurationSection#isSet(java.lang.String)}. - * The default value is false. + * If this is true, all values in the default Configuration will be + * directly copied, making it impossible to distinguish between values + * that were set and values that are provided by default. As a result, + * {@link ConfigurationSection#contains(java.lang.String)} will always + * return the same value as {@link + * ConfigurationSection#isSet(java.lang.String)}. The default value is + * false. * * @param value Whether or not defaults are directly copied * @return This object, for chaining diff --git a/src/main/java/org/bukkit/configuration/ConfigurationSection.java b/src/main/java/org/bukkit/configuration/ConfigurationSection.java index c207e3d6..1bd7fb51 100644 --- a/src/main/java/org/bukkit/configuration/ConfigurationSection.java +++ b/src/main/java/org/bukkit/configuration/ConfigurationSection.java @@ -16,14 +16,15 @@ public interface ConfigurationSection { /** * Gets a set containing all keys in this section. * <p> - * If deep is set to true, then this will contain all the keys within any child - * {@link ConfigurationSection}s (and their children, etc). These will be in a - * valid path notation for you to use. + * If deep is set to true, then this will contain all the keys within any + * child {@link ConfigurationSection}s (and their children, etc). These + * will be in a valid path notation for you to use. * <p> - * If deep is set to false, then this will contain only the keys of any direct children, - * and not their own children. + * If deep is set to false, then this will contain only the keys of any + * direct children, and not their own children. * - * @param deep Whether or not to get a deep list, as opposed to a shallow list. + * @param deep Whether or not to get a deep list, as opposed to a shallow + * list. * @return Set of keys contained within this ConfigurationSection. */ public Set<String> getKeys(boolean deep); @@ -31,14 +32,15 @@ public interface ConfigurationSection { /** * Gets a Map containing all keys and their values for this section. * <p> - * If deep is set to true, then this will contain all the keys and values within - * any child {@link ConfigurationSection}s (and their children, etc). These - * keys will be in a valid path notation for you to use. + * If deep is set to true, then this will contain all the keys and values + * within any child {@link ConfigurationSection}s (and their children, + * etc). These keys will be in a valid path notation for you to use. * <p> - * If deep is set to false, then this will contain only the keys and values of any - * direct children, and not their own children. + * If deep is set to false, then this will contain only the keys and + * values of any direct children, and not their own children. * - * @param deep Whether or not to get a deep list, as opposed to a shallow list. + * @param deep Whether or not to get a deep list, as opposed to a shallow + * list. * @return Map of keys and values of this section. */ public Map<String, Object> getValues(boolean deep); @@ -46,72 +48,80 @@ public interface ConfigurationSection { /** * Checks if this {@link ConfigurationSection} contains the given path. * <p> - * If the value for the requested path does not exist but a default value has - * been specified, this will return true. + * If the value for the requested path does not exist but a default value + * has been specified, this will return true. * * @param path Path to check for existence. - * @return True if this section contains the requested path, either via default or being set. + * @return True if this section contains the requested path, either via + * default or being set. * @throws IllegalArgumentException Thrown when path is null. */ public boolean contains(String path); /** - * Checks if this {@link ConfigurationSection} has a value set for the given path. + * Checks if this {@link ConfigurationSection} has a value set for the + * given path. * <p> - * If the value for the requested path does not exist but a default value has - * been specified, this will still return false. + * If the value for the requested path does not exist but a default value + * has been specified, this will still return false. * * @param path Path to check for existence. - * @return True if this section contains the requested path, regardless of having a default. + * @return True if this section contains the requested path, regardless of + * having a default. * @throws IllegalArgumentException Thrown when path is null. */ public boolean isSet(String path); /** - * Gets the path of this {@link ConfigurationSection} from its root {@link Configuration} + * Gets the path of this {@link ConfigurationSection} from its root {@link + * Configuration} * <p> - * For any {@link Configuration} themselves, this will return an empty string. + * For any {@link Configuration} themselves, this will return an empty + * string. * <p> - * If the section is no longer contained within its root for any reason, such as - * being replaced with a different value, this may return null. + * If the section is no longer contained within its root for any reason, + * such as being replaced with a different value, this may return null. * <p> - * To retrieve the single name of this section, that is, the final part of the path - * returned by this method, you may use {@link #getName()}. + * To retrieve the single name of this section, that is, the final part of + * the path returned by this method, you may use {@link #getName()}. * * @return Path of this section relative to its root */ public String getCurrentPath(); /** - * Gets the name of this individual {@link ConfigurationSection}, in the path. + * Gets the name of this individual {@link ConfigurationSection}, in the + * path. * <p> - * This will always be the final part of {@link #getCurrentPath()}, unless the - * section is orphaned. + * This will always be the final part of {@link #getCurrentPath()}, unless + * the section is orphaned. * * @return Name of this section */ public String getName(); /** - * Gets the root {@link Configuration} that contains this {@link ConfigurationSection} + * Gets the root {@link Configuration} that contains this {@link + * ConfigurationSection} * <p> - * For any {@link Configuration} themselves, this will return its own object. + * For any {@link Configuration} themselves, this will return its own + * object. * <p> - * If the section is no longer contained within its root for any reason, such as - * being replaced with a different value, this may return null. + * If the section is no longer contained within its root for any reason, + * such as being replaced with a different value, this may return null. * * @return Root configuration containing this section. */ public Configuration getRoot(); /** - * Gets the parent {@link ConfigurationSection} that directly contains this - * {@link ConfigurationSection}. + * Gets the parent {@link ConfigurationSection} that directly contains + * this {@link ConfigurationSection}. * <p> * For any {@link Configuration} themselves, this will return null. * <p> - * If the section is no longer contained within its parent for any reason, such as - * being replaced with a different value, this may return null. + * If the section is no longer contained within its parent for any reason, + * such as being replaced with a different value, this may return null. * * @return Parent section containing this section. */ @@ -120,9 +130,9 @@ public interface ConfigurationSection { /** * Gets the requested Object by path. * <p> - * If the Object does not exist but a default value has been specified, this - * will return the default value. If the Object does not exist and no default - * value was specified, this will return null. + * If the Object does not exist but a default value has been specified, + * this will return the default value. If the Object does not exist and no + * default value was specified, this will return null. * * @param path Path of the Object to get. * @return Requested Object. @@ -130,10 +140,12 @@ public interface ConfigurationSection { public Object get(String path); /** - * Gets the requested Object by path, returning a default value if not found. + * Gets the requested Object by path, returning a default value if not + * found. * <p> - * If the Object does not exist then the specified default value will returned - * regardless of if a default has been identified in the root {@link Configuration}. + * If the Object 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 Object to get. * @param def The default value to return if the path is not found. @@ -147,10 +159,10 @@ public interface ConfigurationSection { * If value is null, the entry will be removed. Any existing entry will be * replaced, regardless of what the new value is. * <p> - * Some implementations may have limitations on what you may store. See their - * individual javadocs for details. No implementations should allow you to store - * {@link Configuration}s or {@link ConfigurationSection}s, please use - * {@link #createSection(java.lang.String)} for that. + * Some implementations may have limitations on what you may store. See + * their individual javadocs for details. No implementations should allow + * you to store {@link Configuration}s or {@link ConfigurationSection}s, + * please use {@link #createSection(java.lang.String)} for that. * * @param path Path of the object to set. * @param value New value to set the path to. @@ -160,8 +172,9 @@ public interface ConfigurationSection { /** * Creates an empty {@link ConfigurationSection} at the specified path. * <p> - * Any value that was previously set at this path will be overwritten. If the - * previous value was itself a {@link ConfigurationSection}, it will be orphaned. + * Any value that was previously set at this path will be overwritten. If + * the previous value was itself a {@link ConfigurationSection}, it will + * be orphaned. * * @param path Path to create the section at. * @return Newly created section @@ -169,10 +182,12 @@ public interface ConfigurationSection { public ConfigurationSection createSection(String path); /** - * Creates a {@link ConfigurationSection} at the specified path, with specified values. + * Creates a {@link ConfigurationSection} at the specified path, with + * specified values. * <p> - * Any value that was previously set at this path will be overwritten. If the - * previous value was itself a {@link ConfigurationSection}, it will be orphaned. + * Any value that was previously set at this path will be overwritten. If + * the 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. @@ -184,9 +199,9 @@ public interface ConfigurationSection { /** * Gets the requested String by path. * <p> - * If the String does not exist but a default value has been specified, this - * will return the default value. If the String does not exist and no default - * value was specified, this will return null. + * If the String does not exist but a default value has been specified, + * this will return the default value. If the String does not exist and no + * default value was specified, this will return null. * * @param path Path of the String to get. * @return Requested String. @@ -194,13 +209,16 @@ public interface ConfigurationSection { public String getString(String path); /** - * Gets the requested String by path, returning a default value if not found. + * Gets the requested String by path, returning a default value if not + * found. * <p> - * If the String does not exist then the specified default value will returned - * regardless of if a default has been identified in the root {@link Configuration}. + * If the String 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 String to get. - * @param def The default value to return if the path is not found or is not a String. + * @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); @@ -208,10 +226,10 @@ public interface ConfigurationSection { /** * Checks if the specified path is a String. * <p> - * If the path exists but is not a String, this will return false. If the path does not - * exist, this will return false. If the path does not exist but a default value - * has been specified, this will check if that default value is a String and return - * appropriately. + * If the path exists but is not a String, this will return false. If the + * path does not exist, this will return false. If the path does not exist + * but a default value has been specified, this will check if that default + * value is a String and return appropriately. * * @param path Path of the String to check. * @return Whether or not the specified path is a String. @@ -233,11 +251,13 @@ public interface ConfigurationSection { /** * Gets the requested int by path, returning a default value if not found. * <p> - * If the int does not exist then the specified default value will returned - * regardless of if a default has been identified in the root {@link Configuration}. + * If the int 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 int to get. - * @param def The default value to return if the path is not found or is not an int. + * @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); @@ -245,10 +265,10 @@ public interface ConfigurationSection { /** * Checks if the specified path is an int. * <p> - * If the path exists but is not a int, this will return false. If the path does not - * exist, this will return false. If the path does not exist but a default value - * has been specified, this will check if that default value is a int and return - * appropriately. + * If the path exists but is not a int, this will return false. If the + * path does not exist, this will return false. If the path does not exist + * but a default value has been specified, this will check if that default + * value is a int and return appropriately. * * @param path Path of the int to check. * @return Whether or not the specified path is an int. @@ -258,9 +278,9 @@ public interface ConfigurationSection { /** * Gets the requested boolean by path. * <p> - * If the boolean does not exist but a default value has been specified, this - * will return the default value. If the boolean does not exist and no default - * value was specified, this will return false. + * If the boolean does not exist but a default value has been specified, + * this will return the default value. If the boolean does not exist and + * no default value was specified, this will return false. * * @param path Path of the boolean to get. * @return Requested boolean. @@ -268,13 +288,16 @@ public interface ConfigurationSection { public boolean getBoolean(String path); /** - * Gets the requested boolean by path, returning a default value if not found. + * Gets the requested boolean by path, returning a default value if not + * found. * <p> - * If the boolean does not exist then the specified default value will returned - * regardless of if a default has been identified in the root {@link Configuration}. + * If the boolean 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 boolean to get. - * @param def The default value to return if the path is not found or is not a boolean. + * @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); @@ -282,10 +305,10 @@ public interface ConfigurationSection { /** * Checks if the specified path is a boolean. * <p> - * If the path exists but is not a boolean, this will return false. If the path does not - * exist, this will return false. If the path does not exist but a default value - * has been specified, this will check if that default value is a boolean and return - * appropriately. + * If the path exists but is not a boolean, this will return false. If the + * path does not exist, this will return false. If the path does not exist + * but a default value has been specified, this will check if that default + * value is a boolean and return appropriately. * * @param path Path of the boolean to check. * @return Whether or not the specified path is a boolean. @@ -295,9 +318,9 @@ public interface ConfigurationSection { /** * Gets the requested double by path. * <p> - * If the double does not exist but a default value has been specified, this - * will return the default value. If the double does not exist and no default - * value was specified, this will return 0. + * If the double does not exist but a default value has been specified, + * this will return the default value. If the double does not exist and no + * default value was specified, this will return 0. * * @param path Path of the double to get. * @return Requested double. @@ -305,13 +328,16 @@ public interface ConfigurationSection { public double getDouble(String path); /** - * Gets the requested double by path, returning a default value if not found. + * Gets the requested double by path, returning a default value if not + * found. * <p> - * If the double does not exist then the specified default value will returned - * regardless of if a default has been identified in the root {@link Configuration}. + * If the double 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 double to get. - * @param def The default value to return if the path is not found or is not a double. + * @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); @@ -319,10 +345,10 @@ public interface ConfigurationSection { /** * Checks if the specified path is a double. * <p> - * If the path exists but is not a double, this will return false. If the path does not - * exist, this will return false. If the path does not exist but a default value - * has been specified, this will check if that default value is a double and return - * appropriately. + * If the path exists but is not a double, this will return false. If the + * path does not exist, this will return false. If the path does not exist + * but a default value has been specified, this will check if that default + * value is a double and return appropriately. * * @param path Path of the double to check. * @return Whether or not the specified path is a double. @@ -333,8 +359,8 @@ public interface ConfigurationSection { * Gets the requested long by path. * <p> * If the long does not exist but a default value has been specified, this - * will return the default value. If the long does not exist and no default - * value was specified, this will return 0. + * will return the default value. If the long does not exist and no + * default value was specified, this will return 0. * * @param path Path of the long to get. * @return Requested long. @@ -342,13 +368,16 @@ public interface ConfigurationSection { public long getLong(String path); /** - * Gets the requested long by path, returning a default value if not found. + * Gets the requested long by path, returning a default value if not + * found. * <p> - * If the long does not exist then the specified default value will returned - * regardless of if a default has been identified in the root {@link Configuration}. + * If the long 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 long to get. - * @param def The default value to return if the path is not found or is not a long. + * @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); @@ -356,10 +385,10 @@ public interface ConfigurationSection { /** * Checks if the specified path is a long. * <p> - * If the path exists but is not a long, this will return false. If the path does not - * exist, this will return false. If the path does not exist but a default value - * has been specified, this will check if that default value is a long and return - * appropriately. + * If the path exists but is not a long, this will return false. If the + * path does not exist, this will return false. If the path does not exist + * but a default value has been specified, this will check if that default + * value is a long and return appropriately. * * @param path Path of the long to check. * @return Whether or not the specified path is a long. @@ -371,8 +400,8 @@ public interface ConfigurationSection { * Gets the requested List by path. * <p> * If the List does not exist but a default value has been specified, this - * will return the default value. If the List does not exist and no default - * value was specified, this will return null. + * will return the default value. If the List does not exist and no + * default value was specified, this will return null. * * @param path Path of the List to get. * @return Requested List. @@ -380,13 +409,16 @@ public interface ConfigurationSection { public List<?> getList(String path); /** - * Gets the requested List by path, returning a default value if not found. + * Gets the requested List by path, returning a default value if not + * found. * <p> - * If the List does not exist then the specified default value will returned - * regardless of if a default has been identified in the root {@link Configuration}. + * If the List 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 List to get. - * @param def The default value to return if the path is not found or is not a List. + * @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); @@ -394,10 +426,10 @@ public interface ConfigurationSection { /** * Checks if the specified path is a List. * <p> - * If the path exists but is not a List, this will return false. If the path does not - * exist, this will return false. If the path does not exist but a default value - * has been specified, this will check if that default value is a List and return - * appropriately. + * If the path exists but is not a List, this will return false. If the + * path does not exist, this will return false. If the path does not exist + * but a default value has been specified, this will check if that default + * value is a List and return appropriately. * * @param path Path of the List to check. * @return Whether or not the specified path is a List. @@ -408,11 +440,11 @@ public interface ConfigurationSection { * Gets the requested List of String by path. * <p> * If the List does not exist but a default value has been specified, this - * will return the default value. If the List does not exist and no default - * value was specified, this will return an empty List. + * will return the default value. If the List does not exist and no + * default value was specified, this will return an empty List. * <p> - * This method will attempt to cast any values into a String if possible, but may - * miss any values out if they are not compatible. + * This method will attempt to cast any values into a String if possible, + * but may miss any values out if they are not compatible. * * @param path Path of the List to get. * @return Requested List of String. @@ -423,11 +455,11 @@ public interface ConfigurationSection { * Gets the requested List of Integer by path. * <p> * If the List does not exist but a default value has been specified, this - * will return the default value. If the List does not exist and no default - * value was specified, this will return an empty List. + * will return the default value. If the List does not exist and no + * default value was specified, this will return an empty List. * <p> - * This method will attempt to cast any values into a Integer if possible, but may - * miss any values out if they are not compatible. + * This method will attempt to cast any values into a Integer if possible, + * but may miss any values out if they are not compatible. * * @param path Path of the List to get. * @return Requested List of Integer. @@ -438,11 +470,11 @@ public interface ConfigurationSection { * Gets the requested List of Boolean by path. * <p> * If the List does not exist but a default value has been specified, this - * will return the default value. If the List does not exist and no default - * value was specified, this will return an empty List. + * will return the default value. If the List does not exist and no + * default value was specified, this will return an empty List. * <p> - * This method will attempt to cast any values into a Boolean if possible, but may - * miss any values out if they are not compatible. + * This method will attempt to cast any values into a Boolean if possible, + * but may miss any values out if they are not compatible. * * @param path Path of the List to get. * @return Requested List of Boolean. @@ -453,11 +485,11 @@ public interface ConfigurationSection { * Gets the requested List of Double by path. * <p> * If the List does not exist but a default value has been specified, this - * will return the default value. If the List does not exist and no default - * value was specified, this will return an empty List. + * will return the default value. If the List does not exist and no + * default value was specified, this will return an empty List. * <p> - * This method will attempt to cast any values into a Double if possible, but may - * miss any values out if they are not compatible. + * This method will attempt to cast any values into a Double if possible, + * but may miss any values out if they are not compatible. * * @param path Path of the List to get. * @return Requested List of Double. @@ -468,11 +500,11 @@ public interface ConfigurationSection { * Gets the requested List of Float by path. * <p> * If the List does not exist but a default value has been specified, this - * will return the default value. If the List does not exist and no default - * value was specified, this will return an empty List. + * will return the default value. If the List does not exist and no + * default value was specified, this will return an empty List. * <p> - * This method will attempt to cast any values into a Float if possible, but may - * miss any values out if they are not compatible. + * This method will attempt to cast any values into a Float if possible, + * but may miss any values out if they are not compatible. * * @param path Path of the List to get. * @return Requested List of Float. @@ -483,11 +515,11 @@ public interface ConfigurationSection { * Gets the requested List of Long by path. * <p> * If the List does not exist but a default value has been specified, this - * will return the default value. If the List does not exist and no default - * value was specified, this will return an empty List. + * will return the default value. If the List does not exist and no + * default value was specified, this will return an empty List. * <p> - * This method will attempt to cast any values into a Long if possible, but may - * miss any values out if they are not compatible. + * This method will attempt to cast any values into a Long if possible, + * but may miss any values out if they are not compatible. * * @param path Path of the List to get. * @return Requested List of Long. @@ -498,11 +530,11 @@ public interface ConfigurationSection { * Gets the requested List of Byte by path. * <p> * If the List does not exist but a default value has been specified, this - * will return the default value. If the List does not exist and no default - * value was specified, this will return an empty List. + * will return the default value. If the List does not exist and no + * default value was specified, this will return an empty List. * <p> - * This method will attempt to cast any values into a Byte if possible, but may - * miss any values out if they are not compatible. + * This method will attempt to cast any values into a Byte if possible, + * but may miss any values out if they are not compatible. * * @param path Path of the List to get. * @return Requested List of Byte. @@ -513,11 +545,11 @@ public interface ConfigurationSection { * Gets the requested List of Character by path. * <p> * If the List does not exist but a default value has been specified, this - * will return the default value. If the List does not exist and no default - * value was specified, this will return an empty List. + * will return the default value. If the List does not exist and no + * default value was specified, this will return an empty List. * <p> - * This method will attempt to cast any values into a Character if possible, but may - * miss any values out if they are not compatible. + * This method will attempt to cast any values into a Character if + * possible, but may miss any values out if they are not compatible. * * @param path Path of the List to get. * @return Requested List of Character. @@ -528,11 +560,11 @@ public interface ConfigurationSection { * Gets the requested List of Short by path. * <p> * If the List does not exist but a default value has been specified, this - * will return the default value. If the List does not exist and no default - * value was specified, this will return an empty List. + * will return the default value. If the List does not exist and no + * default value was specified, this will return an empty List. * <p> - * This method will attempt to cast any values into a Short if possible, but may - * miss any values out if they are not compatible. + * This method will attempt to cast any values into a Short if possible, + * but may miss any values out if they are not compatible. * * @param path Path of the List to get. * @return Requested List of Short. @@ -543,11 +575,11 @@ public interface ConfigurationSection { * Gets the requested List of Maps by path. * <p> * If the List does not exist but a default value has been specified, this - * will return the default value. If the List does not exist and no default - * value was specified, this will return an empty List. + * will return the default value. If the List does not exist and no + * default value was specified, this will return an empty List. * <p> - * This method will attempt to cast any values into a Map if possible, but may - * miss any values out if they are not compatible. + * This method will attempt to cast any values into a Map if possible, but + * may miss any values out if they are not compatible. * * @param path Path of the List to get. * @return Requested List of Maps. @@ -558,9 +590,9 @@ public interface ConfigurationSection { /** * Gets the requested Vector by path. * <p> - * If the Vector does not exist but a default value has been specified, this - * will return the default value. If the Vector does not exist and no default - * value was specified, this will return null. + * If the Vector does not exist but a default value has been specified, + * this will return the default value. If the Vector does not exist and no + * default value was specified, this will return null. * * @param path Path of the Vector to get. * @return Requested Vector. @@ -568,13 +600,16 @@ public interface ConfigurationSection { public Vector getVector(String path); /** - * Gets the requested {@link 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}. + * 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. + * @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); @@ -582,10 +617,10 @@ public interface ConfigurationSection { /** * Checks if the specified path is a Vector. * <p> - * If the path exists but is not a Vector, this will return false. If the path does not - * exist, this will return false. If the path does not exist but a default value - * has been specified, this will check if that default value is a Vector and return - * appropriately. + * If the path exists but is not a Vector, this will return false. If the + * path does not exist, this will return false. If the path does not exist + * but a default value has been specified, this will check if that default + * value is a Vector and return appropriately. * * @param path Path of the Vector to check. * @return Whether or not the specified path is a Vector. @@ -595,9 +630,10 @@ public interface ConfigurationSection { /** * Gets the requested OfflinePlayer by path. * <p> - * If the OfflinePlayer does not exist but a default value has been specified, this - * will return the default value. If the OfflinePlayer does not exist and no default - * value was specified, this will return null. + * If the OfflinePlayer does not exist but a default value has been + * specified, this will return the default value. If the OfflinePlayer + * does not exist and no default value was specified, this will return + * null. * * @param path Path of the OfflinePlayer to get. * @return Requested OfflinePlayer. @@ -605,13 +641,16 @@ public interface ConfigurationSection { public OfflinePlayer getOfflinePlayer(String path); /** - * Gets the requested {@link 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}. + * 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. + * @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); @@ -619,10 +658,10 @@ public interface ConfigurationSection { /** * Checks if the specified path is an OfflinePlayer. * <p> - * If the path exists but is not a OfflinePlayer, this will return false. If the path does not - * exist, this will return false. If the path does not exist but a default value - * has been specified, this will check if that default value is a OfflinePlayer and return - * appropriately. + * If the path exists but is not a OfflinePlayer, this will return false. + * If the path does not exist, this will return false. If the path does + * not exist but a default value has been specified, this will check if + * that default value is a OfflinePlayer and return appropriately. * * @param path Path of the OfflinePlayer to check. * @return Whether or not the specified path is an OfflinePlayer. @@ -632,9 +671,9 @@ public interface ConfigurationSection { /** * Gets the requested ItemStack by path. * <p> - * If the ItemStack does not exist but a default value has been specified, this - * will return the default value. If the ItemStack does not exist and no default - * value was specified, this will return null. + * If the ItemStack does not exist but a default value has been specified, + * this will return the default value. If the ItemStack does not exist and + * no default value was specified, this will return null. * * @param path Path of the ItemStack to get. * @return Requested ItemStack. @@ -642,13 +681,16 @@ public interface ConfigurationSection { public ItemStack getItemStack(String path); /** - * Gets the requested {@link 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}. + * 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. + * @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); @@ -656,10 +698,10 @@ public interface ConfigurationSection { /** * Checks if the specified path is an ItemStack. * <p> - * If the path exists but is not a ItemStack, this will return false. If the path does not - * exist, this will return false. If the path does not exist but a default value - * has been specified, this will check if that default value is a ItemStack and return - * appropriately. + * If the path exists but is not a ItemStack, this will return false. If + * the path does not exist, this will return false. If the path does not + * exist but a default value has been specified, this will check if that + * default value is a ItemStack and return appropriately. * * @param path Path of the ItemStack to check. * @return Whether or not the specified path is an ItemStack. @@ -669,9 +711,9 @@ public interface ConfigurationSection { /** * Gets the requested Color by path. * <p> - * If the Color does not exist but a default value has been specified, this - * will return the default value. If the Color does not exist and no default - * value was specified, this will return null. + * If the Color does not exist but a default value has been specified, + * this will return the default value. If the Color does not exist and no + * default value was specified, this will return null. * * @param path Path of the Color to get. * @return Requested Color. @@ -679,13 +721,16 @@ public interface ConfigurationSection { public Color getColor(String path); /** - * Gets the requested {@link Color} by path, returning a default value if not found. + * Gets the requested {@link Color} by path, returning a default value if + * not found. * <p> - * If the Color does not exist then the specified default value will returned - * regardless of if a default has been identified in the root {@link Configuration}. + * If the Color 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 Color to get. - * @param def The default value to return if the path is not found or is not an Color. + * @param def The default value to return if the path is not found or is + * not a Color. * @return Requested Color. */ public Color getColor(String path, Color def); @@ -693,22 +738,23 @@ public interface ConfigurationSection { /** * Checks if the specified path is a Color. * <p> - * If the path exists but is not a Color, this will return false. If the path does not - * exist, this will return false. If the path does not exist but a default value - * has been specified, this will check if that default value is a Color and return - * appropriately. + * If the path exists but is not a Color, this will return false. If the + * path does not exist, this will return false. If the path does not exist + * but a default value has been specified, this will check if that default + * value is a Color and return appropriately. * * @param path Path of the Color to check. - * @return Whether or not the specified path is an Color. + * @return Whether or not the specified path is a Color. */ public boolean isColor(String path); /** * Gets the requested ConfigurationSection by path. * <p> - * If the ConfigurationSection does not exist but a default value has been specified, this - * will return the default value. If the ConfigurationSection does not exist and no default - * value was specified, this will return null. + * If the ConfigurationSection does not exist but a default value has been + * specified, this will return the default value. If the + * ConfigurationSection does not exist and no default value was specified, + * this will return null. * * @param path Path of the ConfigurationSection to get. * @return Requested ConfigurationSection. @@ -718,9 +764,10 @@ public interface ConfigurationSection { /** * Checks if the specified path is a ConfigurationSection. * <p> - * If the path exists but is not a ConfigurationSection, this will return false. If the path does not - * exist, this will return false. If the path does not exist but a default value - * has been specified, this will check if that default value is a ConfigurationSection and return + * If the path exists but is not a ConfigurationSection, this will return + * false. If the path does not exist, this will return false. If the path + * does not exist but a default value has been specified, this will check + * if that default value is a ConfigurationSection and return * appropriately. * * @param path Path of the ConfigurationSection to check. @@ -729,11 +776,12 @@ public interface ConfigurationSection { public boolean isConfigurationSection(String path); /** - * Gets the equivalent {@link ConfigurationSection} from the default {@link Configuration} defined in {@link #getRoot()}. + * Gets the equivalent {@link ConfigurationSection} from the default + * {@link Configuration} defined in {@link #getRoot()}. * <p> - * If the root contains no defaults, or the defaults doesn't contain a value - * for this path, or the value at this path is not a {@link ConfigurationSection} then - * this will return null. + * If the root contains no defaults, or the defaults doesn't contain a + * value for this path, or the value at this path is not a {@link + * ConfigurationSection} then this will return null. * * @return Equivalent section in root configuration */ @@ -742,15 +790,16 @@ public interface ConfigurationSection { /** * Sets the default value in the root at the given path as provided. * <p> - * If no source {@link Configuration} was provided as a default collection, - * then a new {@link MemoryConfiguration} will be created to hold the new default - * value. + * If no source {@link Configuration} was provided as a default + * collection, then a new {@link MemoryConfiguration} will be created to + * hold the new default value. * <p> - * If value is null, the value will be removed from the default Configuration source. + * If value is null, the value will be removed from the default + * Configuration source. * <p> - * If the value as returned by {@link #getDefaultSection()} is null, - * then this will create a new section at the path, replacing anything that - * may have existed there previously. + * If the value as returned by {@link #getDefaultSection()} is null, then + * this will create a new section at the path, replacing anything that may + * have existed there previously. * * @param path Path of the value to set. * @param value Value to set the default to. diff --git a/src/main/java/org/bukkit/configuration/InvalidConfigurationException.java b/src/main/java/org/bukkit/configuration/InvalidConfigurationException.java index 81432139..d23480e5 100644 --- a/src/main/java/org/bukkit/configuration/InvalidConfigurationException.java +++ b/src/main/java/org/bukkit/configuration/InvalidConfigurationException.java @@ -7,12 +7,14 @@ package org.bukkit.configuration; public class InvalidConfigurationException extends Exception { /** - * Creates a new instance of InvalidConfigurationException without a message or cause. + * Creates a new instance of InvalidConfigurationException without a + * message or cause. */ public InvalidConfigurationException() {} /** - * Constructs an instance of InvalidConfigurationException with the specified message. + * Constructs an instance of InvalidConfigurationException with the + * specified message. * * @param msg The details of the exception. */ @@ -21,7 +23,8 @@ public class InvalidConfigurationException extends Exception { } /** - * Constructs an instance of InvalidConfigurationException with the specified cause. + * Constructs an instance of InvalidConfigurationException with the + * specified cause. * * @param cause The cause of the exception. */ @@ -30,7 +33,8 @@ public class InvalidConfigurationException extends Exception { } /** - * Constructs an instance of InvalidConfigurationException with the specified message and cause. + * Constructs an instance of InvalidConfigurationException with the + * specified message and cause. * * @param cause The cause of the exception. * @param msg The details of the exception. diff --git a/src/main/java/org/bukkit/configuration/MemoryConfiguration.java b/src/main/java/org/bukkit/configuration/MemoryConfiguration.java index 7eaeff34..19c27a1c 100644 --- a/src/main/java/org/bukkit/configuration/MemoryConfiguration.java +++ b/src/main/java/org/bukkit/configuration/MemoryConfiguration.java @@ -19,8 +19,8 @@ public class MemoryConfiguration extends MemorySection implements Configuration public MemoryConfiguration() {} /** - * Creates an empty {@link MemoryConfiguration} using the specified {@link Configuration} - * as a source for all default values. + * Creates an empty {@link MemoryConfiguration} using the specified {@link + * Configuration} as a source for all default values. * * @param defaults Default value provider * @throws IllegalArgumentException Thrown if defaults is null diff --git a/src/main/java/org/bukkit/configuration/MemoryConfigurationOptions.java b/src/main/java/org/bukkit/configuration/MemoryConfigurationOptions.java index 16b10514..44c046c4 100644 --- a/src/main/java/org/bukkit/configuration/MemoryConfigurationOptions.java +++ b/src/main/java/org/bukkit/configuration/MemoryConfigurationOptions.java @@ -1,7 +1,8 @@ package org.bukkit.configuration; /** - * Various settings for controlling the input and output of a {@link MemoryConfiguration} + * Various settings for controlling the input and output of a {@link + * MemoryConfiguration} */ public class MemoryConfigurationOptions extends ConfigurationOptions { protected MemoryConfigurationOptions(MemoryConfiguration configuration) { diff --git a/src/main/java/org/bukkit/configuration/MemorySection.java b/src/main/java/org/bukkit/configuration/MemorySection.java index e20121e2..f180bf5f 100644 --- a/src/main/java/org/bukkit/configuration/MemorySection.java +++ b/src/main/java/org/bukkit/configuration/MemorySection.java @@ -26,12 +26,14 @@ public class MemorySection implements ConfigurationSection { private final String fullPath; /** - * Creates an empty MemorySection for use as a root {@link Configuration} section. + * Creates an empty MemorySection for use as a root {@link Configuration} + * section. * <p> - * Note that calling this without being yourself a {@link Configuration} will throw an - * exception! + * Note that calling this without being yourself a {@link Configuration} + * will throw an exception! * - * @throws IllegalStateException Thrown if this is not a {@link Configuration} root. + * @throws IllegalStateException Thrown if this is not a {@link + * Configuration} root. */ protected MemorySection() { if (!(this instanceof Configuration)) { @@ -48,8 +50,10 @@ public class MemorySection implements ConfigurationSection { * Creates an empty MemorySection with the specified parent and path. * * @param parent Parent section that contains this own section. - * @param path Path that you may access this section from via the root {@link Configuration}. - * @throws IllegalArgumentException Thrown is parent or path is null, or if parent contains no root Configuration. + * @param path Path that you may access this section from via the root + * {@link Configuration}. + * @throws IllegalArgumentException Thrown is parent or path is null, or + * if parent contains no root Configuration. */ protected MemorySection(ConfigurationSection parent, String path) { Validate.notNull(parent, "Parent cannot be null"); @@ -745,9 +749,11 @@ public class MemorySection implements ConfigurationSection { } /** - * Creates a full path to the given {@link ConfigurationSection} from its root {@link Configuration}. + * Creates a full path to the given {@link ConfigurationSection} from its + * root {@link Configuration}. * <p> - * You may use this method for any given {@link ConfigurationSection}, not only {@link MemorySection}. + * You may use this method for any given {@link ConfigurationSection}, not + * only {@link MemorySection}. * * @param section Section to create a path for. * @param key Name of the specified section. @@ -758,9 +764,11 @@ public class MemorySection implements ConfigurationSection { } /** - * Creates a relative path to the given {@link ConfigurationSection} from the given relative section. + * Creates a relative path to the given {@link ConfigurationSection} from + * the given relative section. * <p> - * You may use this method for any given {@link ConfigurationSection}, not only {@link MemorySection}. + * You may use this method for any given {@link ConfigurationSection}, not + * only {@link MemorySection}. * * @param section Section to create a path for. * @param key Name of the specified section. diff --git a/src/main/java/org/bukkit/configuration/file/FileConfiguration.java b/src/main/java/org/bukkit/configuration/file/FileConfiguration.java index 33aac313..3f9992e7 100644 --- a/src/main/java/org/bukkit/configuration/file/FileConfiguration.java +++ b/src/main/java/org/bukkit/configuration/file/FileConfiguration.java @@ -16,7 +16,8 @@ import org.bukkit.configuration.Configuration; import org.bukkit.configuration.MemoryConfiguration; /** - * This is a base class for all File based implementations of {@link Configuration} + * This is a base class for all File based implementations of {@link + * Configuration} */ public abstract class FileConfiguration extends MemoryConfiguration { /** @@ -27,8 +28,8 @@ public abstract class FileConfiguration extends MemoryConfiguration { } /** - * Creates an empty {@link FileConfiguration} using the specified {@link Configuration} - * as a source for all default values. + * Creates an empty {@link FileConfiguration} using the specified {@link + * Configuration} as a source for all default values. * * @param defaults Default value provider */ @@ -39,11 +40,13 @@ public abstract class FileConfiguration extends MemoryConfiguration { /** * Saves this {@link FileConfiguration} to the specified location. * <p> - * If the file does not exist, it will be created. If already exists, it will - * be overwritten. If it cannot be overwritten or created, an exception will be thrown. + * If the file does not exist, it will be created. If already exists, it + * will be overwritten. If it cannot be overwritten or created, an + * exception will be thrown. * * @param file File to save to. - * @throws IOException Thrown when the given file cannot be written to for any reason. + * @throws IOException Thrown when the given file cannot be written to for + * any reason. * @throws IllegalArgumentException Thrown when file is null. */ public void save(File file) throws IOException { @@ -65,11 +68,13 @@ public abstract class FileConfiguration extends MemoryConfiguration { /** * Saves this {@link FileConfiguration} to the specified location. * <p> - * If the file does not exist, it will be created. If already exists, it will - * be overwritten. If it cannot be overwritten or created, an exception will be thrown. + * If the file does not exist, it will be created. If already exists, it + * will be overwritten. If it cannot be overwritten or created, an + * exception will be thrown. * * @param file File to save to. - * @throws IOException Thrown when the given file cannot be written to for any reason. + * @throws IOException Thrown when the given file cannot be written to for + * any reason. * @throws IllegalArgumentException Thrown when file is null. */ public void save(String file) throws IOException { @@ -88,15 +93,19 @@ public abstract class FileConfiguration extends MemoryConfiguration { /** * Loads this {@link FileConfiguration} from the specified location. * <p> - * All the values contained within this configuration will be removed, leaving - * only settings and defaults, and the new values will be loaded from the given file. + * All the values contained within this configuration will be removed, + * leaving only settings and defaults, and the new values will be loaded + * from the given file. * <p> - * If the file cannot be loaded for any reason, an exception will be thrown. + * If the file cannot be loaded for any reason, an exception will be + * thrown. * * @param file File to load from. - * @throws FileNotFoundException Thrown when the given file cannot be opened. + * @throws FileNotFoundException Thrown when the given file cannot be + * opened. * @throws IOException Thrown when the given file cannot be read. - * @throws InvalidConfigurationException Thrown when the given file is not a valid Configuration. + * @throws InvalidConfigurationException Thrown when the given file is not + * a valid Configuration. * @throws IllegalArgumentException Thrown when file is null. */ public void load(File file) throws FileNotFoundException, IOException, InvalidConfigurationException { @@ -108,12 +117,14 @@ public abstract class FileConfiguration extends MemoryConfiguration { /** * Loads this {@link FileConfiguration} from the specified stream. * <p> - * All the values contained within this configuration will be removed, leaving - * only settings and defaults, and the new values will be loaded from the given stream. + * All the values contained within this configuration will be removed, + * leaving only settings and defaults, and the new values will be loaded + * from the given stream. * * @param stream Stream to load from * @throws IOException Thrown when the given file cannot be read. - * @throws InvalidConfigurationException Thrown when the given file is not a valid Configuration. + * @throws InvalidConfigurationException Thrown when the given file is not + * a valid Configuration. * @throws IllegalArgumentException Thrown when stream is null. */ public void load(InputStream stream) throws IOException, InvalidConfigurationException { @@ -141,15 +152,19 @@ public abstract class FileConfiguration extends MemoryConfiguration { /** * Loads this {@link FileConfiguration} from the specified location. * <p> - * All the values contained within this configuration will be removed, leaving - * only settings and defaults, and the new values will be loaded from the given file. + * All the values contained within this configuration will be removed, + * leaving only settings and defaults, and the new values will be loaded + * from the given file. * <p> - * If the file cannot be loaded for any reason, an exception will be thrown. + * If the file cannot be loaded for any reason, an exception will be + * thrown. * * @param file File to load from. - * @throws FileNotFoundException Thrown when the given file cannot be opened. + * @throws FileNotFoundException Thrown when the given file cannot be + * opened. * @throws IOException Thrown when the given file cannot be read. - * @throws InvalidConfigurationException Thrown when the given file is not a valid Configuration. + * @throws InvalidConfigurationException Thrown when the given file is not + * a valid Configuration. * @throws IllegalArgumentException Thrown when file is null. */ public void load(String file) throws FileNotFoundException, IOException, InvalidConfigurationException { @@ -159,24 +174,29 @@ public abstract class FileConfiguration extends MemoryConfiguration { } /** - * Loads this {@link FileConfiguration} from the specified string, as opposed to from file. + * Loads this {@link FileConfiguration} from the specified string, as + * opposed to from file. * <p> - * All the values contained within this configuration will be removed, leaving - * only settings and defaults, and the new values will be loaded from the given string. + * All the values contained within this configuration will be removed, + * leaving only settings and defaults, and the new values will be loaded + * from the given string. * <p> * If the string is invalid in any way, an exception will be thrown. * * @param contents Contents of a Configuration to load. - * @throws InvalidConfigurationException Thrown if the specified string is invalid. + * @throws InvalidConfigurationException Thrown if the specified string is + * invalid. * @throws IllegalArgumentException Thrown if contents is null. */ public abstract void loadFromString(String contents) throws InvalidConfigurationException; /** - * Compiles the header for this {@link FileConfiguration} and returns the result. + * Compiles the header for this {@link FileConfiguration} and returns the + * result. * <p> - * This will use the header from {@link #options()} -> {@link FileConfigurationOptions#header()}, - * respecting the rules of {@link FileConfigurationOptions#copyHeader()} if set. + * This will use the header from {@link #options()} -> {@link + * FileConfigurationOptions#header()}, respecting the rules of {@link + * FileConfigurationOptions#copyHeader()} if set. * * @return Compiled header */ diff --git a/src/main/java/org/bukkit/configuration/file/FileConfigurationOptions.java b/src/main/java/org/bukkit/configuration/file/FileConfigurationOptions.java index 3d225443..ccf81e06 100644 --- a/src/main/java/org/bukkit/configuration/file/FileConfigurationOptions.java +++ b/src/main/java/org/bukkit/configuration/file/FileConfigurationOptions.java @@ -3,7 +3,8 @@ package org.bukkit.configuration.file; import org.bukkit.configuration.*; /** - * Various settings for controlling the input and output of a {@link FileConfiguration} + * Various settings for controlling the input and output of a {@link + * FileConfiguration} */ public class FileConfigurationOptions extends MemoryConfigurationOptions { private String header = null; @@ -33,13 +34,14 @@ public class FileConfigurationOptions extends MemoryConfigurationOptions { /** * Gets the header that will be applied to the top of the saved output. * <p> - * This header will be commented out and applied directly at the top of the - * generated output of the {@link FileConfiguration}. It is not required to - * include a newline at the end of the header as it will automatically be applied, - * but you may include one if you wish for extra spacing. + * This header will be commented out and applied directly at the top of + * the generated output of the {@link FileConfiguration}. It is not + * required to include a newline at the end of the header as it will + * automatically be applied, but you may include one if you wish for extra + * spacing. * <p> - * Null is a valid value which will indicate that no header is to be applied. - * The default value is null. + * Null is a valid value which will indicate that no header is to be + * applied. The default value is null. * * @return Header */ @@ -50,12 +52,14 @@ public class FileConfigurationOptions extends MemoryConfigurationOptions { /** * Sets the header that will be applied to the top of the saved output. * <p> - * This header will be commented out and applied directly at the top of the - * generated output of the {@link FileConfiguration}. It is not required to - * include a newline at the end of the header as it will automatically be applied, - * but you may include one if you wish for extra spacing. + * This header will be commented out and applied directly at the top of + * the generated output of the {@link FileConfiguration}. It is not + * required to include a newline at the end of the header as it will + * automatically be applied, but you may include one if you wish for extra + * spacing. * <p> - * Null is a valid value which will indicate that no header is to be applied. + * Null is a valid value which will indicate that no header is to be + * applied. * * @param value New header * @return This object, for chaining @@ -69,12 +73,15 @@ public class FileConfigurationOptions extends MemoryConfigurationOptions { * Gets whether or not the header should be copied from a default source. * <p> * If this is true, if a default {@link FileConfiguration} is passed to - * {@link FileConfiguration#setDefaults(org.bukkit.configuration.Configuration)} - * then upon saving it will use the header from that config, instead of the one provided here. + * {@link + * FileConfiguration#setDefaults(org.bukkit.configuration.Configuration)} + * then upon saving it will use the header from that config, instead of + * the one provided here. * <p> - * If no default is set on the configuration, or the default is not of type FileConfiguration, - * or that config has no header ({@link #header()} returns null) then the header - * specified in this configuration will be used. + * If no default is set on the configuration, or the default is not of + * type FileConfiguration, or that config has no header ({@link #header()} + * returns null) then the header specified in this configuration will be + * used. * <p> * Defaults to true. * @@ -88,12 +95,15 @@ public class FileConfigurationOptions extends MemoryConfigurationOptions { * Sets whether or not the header should be copied from a default source. * <p> * If this is true, if a default {@link FileConfiguration} is passed to - * {@link FileConfiguration#setDefaults(org.bukkit.configuration.Configuration)} - * then upon saving it will use the header from that config, instead of the one provided here. + * {@link + * FileConfiguration#setDefaults(org.bukkit.configuration.Configuration)} + * then upon saving it will use the header from that config, instead of + * the one provided here. * <p> - * If no default is set on the configuration, or the default is not of type FileConfiguration, - * or that config has no header ({@link #header()} returns null) then the header - * specified in this configuration will be used. + * If no default is set on the configuration, or the default is not of + * type FileConfiguration, or that config has no header ({@link #header()} + * returns null) then the header specified in this configuration will be + * used. * <p> * Defaults to true. * diff --git a/src/main/java/org/bukkit/configuration/file/YamlConfiguration.java b/src/main/java/org/bukkit/configuration/file/YamlConfiguration.java index 98247538..18be0dc6 100644 --- a/src/main/java/org/bukkit/configuration/file/YamlConfiguration.java +++ b/src/main/java/org/bukkit/configuration/file/YamlConfiguration.java @@ -160,7 +160,8 @@ public class YamlConfiguration extends FileConfiguration { * Creates a new {@link YamlConfiguration}, loading from the given file. * <p> * Any errors loading the Configuration will be logged and then ignored. - * If the specified input is not a valid config, a blank config will be returned. + * If the specified input is not a valid config, a blank config will be + * returned. * * @param file Input file * @return Resulting configuration @@ -187,7 +188,8 @@ public class YamlConfiguration extends FileConfiguration { * Creates a new {@link YamlConfiguration}, loading from the given stream. * <p> * Any errors loading the Configuration will be logged and then ignored. - * If the specified input is not a valid config, a blank config will be returned. + * If the specified input is not a valid config, a blank config will be + * returned. * * @param stream Input stream * @return Resulting configuration diff --git a/src/main/java/org/bukkit/configuration/file/YamlConfigurationOptions.java b/src/main/java/org/bukkit/configuration/file/YamlConfigurationOptions.java index d2dd712f..57894e32 100644 --- a/src/main/java/org/bukkit/configuration/file/YamlConfigurationOptions.java +++ b/src/main/java/org/bukkit/configuration/file/YamlConfigurationOptions.java @@ -3,7 +3,8 @@ package org.bukkit.configuration.file; import org.apache.commons.lang.Validate; /** - * Various settings for controlling the input and output of a {@link YamlConfiguration} + * Various settings for controlling the input and output of a {@link + * YamlConfiguration} */ public class YamlConfigurationOptions extends FileConfigurationOptions { private int indent = 2; diff --git a/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerializable.java b/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerializable.java index 7bf4b299..ba3c8c47 100644 --- a/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerializable.java +++ b/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerializable.java @@ -5,17 +5,18 @@ import java.util.Map; /** * Represents an object that may be serialized. * <p> - * These objects MUST implement one of the following, in addition to the methods - * as defined by this interface: + * 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}<{@link String}, {@link Object}> - * and returns the class.</li> - * <li>A static method "valueOf" that accepts a single {@link Map}<{@link String}, {@link Object}> - * and returns the class.</li> - * <li>A constructor that accepts a single {@link Map}<{@link String}, {@link Object}>.</li> + * <li>A static method "deserialize" that accepts a single {@link Map}< + * {@link String}, {@link Object}> and returns the class.</li> + * <li>A static method "valueOf" that accepts a single {@link Map}<{@link + * String}, {@link Object}> and returns the class.</li> + * <li>A constructor that accepts a single {@link Map}<{@link String}, + * {@link Object}>.</li> * </ul> - * In addition to implementing this interface, you must register the class with - * {@link ConfigurationSerialization#registerClass(Class)}. + * In addition to implementing this interface, you must register the class + * with {@link ConfigurationSerialization#registerClass(Class)}. * * @see DelegateDeserialization * @see SerializableAs @@ -25,8 +26,8 @@ public interface ConfigurationSerializable { /** * Creates a Map representation of this class. * <p> - * This class must provide a method to restore this class, as defined in the - * {@link ConfigurationSerializable} interface javadocs. + * This class must provide a method to restore this class, as defined in + * the {@link ConfigurationSerializable} interface javadocs. * * @return Map containing the current state of this class */ diff --git a/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerialization.java b/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerialization.java index e6a07f95..96a806f1 100644 --- a/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerialization.java +++ b/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerialization.java @@ -134,13 +134,15 @@ public class ConfigurationSerialization { } /** - * Attempts to deserialize the given arguments into a new instance of the given class. + * Attempts to deserialize the given arguments into a new instance of the + * given class. * <p> - * The class must implement {@link ConfigurationSerializable}, including the extra methods - * as specified in the javadoc of ConfigurationSerializable. + * The class must implement {@link ConfigurationSerializable}, including + * the extra methods as specified in the javadoc of + * ConfigurationSerializable. * <p> - * If a new instance could not be made, an example being the class not fully implementing - * the interface, null will be returned. + * If a new instance could not be made, an example being the class not + * fully implementing the interface, null will be returned. * * @param args Arguments for deserialization * @param clazz Class to deserialize into @@ -151,13 +153,15 @@ public class ConfigurationSerialization { } /** - * Attempts to deserialize the given arguments into a new instance of the given class. + * Attempts to deserialize the given arguments into a new instance of the + * given class. * <p> - * The class must implement {@link ConfigurationSerializable}, including the extra methods - * as specified in the javadoc of ConfigurationSerializable. + * The class must implement {@link ConfigurationSerializable}, including + * the extra methods as specified in the javadoc of + * ConfigurationSerializable. * <p> - * If a new instance could not be made, an example being the class not fully implementing - * the interface, null will be returned. + * If a new instance could not be made, an example being the class not + * fully implementing the interface, null will be returned. * * @param args Arguments for deserialization * @return New instance of the specified class @@ -188,7 +192,8 @@ public class ConfigurationSerialization { } /** - * Registers the given {@link ConfigurationSerializable} class by its alias + * Registers the given {@link ConfigurationSerializable} class by its + * alias * * @param clazz Class to register */ @@ -202,7 +207,8 @@ public class ConfigurationSerialization { } /** - * Registers the given alias to the specified {@link ConfigurationSerializable} class + * Registers the given alias to the specified {@link + * ConfigurationSerializable} class * * @param clazz Class to register * @param alias Alias to register as @@ -222,7 +228,8 @@ public class ConfigurationSerialization { } /** - * Unregisters any aliases for the specified {@link ConfigurationSerializable} class + * Unregisters any aliases for the specified {@link + * ConfigurationSerializable} class * * @param clazz Class to unregister */ @@ -233,7 +240,8 @@ public class ConfigurationSerialization { } /** - * Attempts to get a registered {@link ConfigurationSerializable} class by its alias + * Attempts to get a registered {@link ConfigurationSerializable} class by + * its alias * * @param alias Alias of the serializable * @return Registered class, or null if not found @@ -243,7 +251,8 @@ public class ConfigurationSerialization { } /** - * Gets the correct alias for the given {@link ConfigurationSerializable} class + * Gets the correct alias for the given {@link ConfigurationSerializable} + * class * * @param clazz Class to get alias for * @return Alias to use for the class diff --git a/src/main/java/org/bukkit/configuration/serialization/DelegateDeserialization.java b/src/main/java/org/bukkit/configuration/serialization/DelegateDeserialization.java index 437d7108..1cfae94f 100644 --- a/src/main/java/org/bukkit/configuration/serialization/DelegateDeserialization.java +++ b/src/main/java/org/bukkit/configuration/serialization/DelegateDeserialization.java @@ -6,14 +6,15 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Applies to a {@link ConfigurationSerializable} that will delegate all deserialization to another - * {@link ConfigurationSerializable}. + * Applies to a {@link ConfigurationSerializable} that will delegate all + * deserialization to another {@link ConfigurationSerializable}. */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) public @interface DelegateDeserialization { /** - * Which class should be used as a delegate for this classes deserialization + * Which class should be used as a delegate for this classes + * deserialization * * @return Delegate class */ diff --git a/src/main/java/org/bukkit/configuration/serialization/SerializableAs.java b/src/main/java/org/bukkit/configuration/serialization/SerializableAs.java index 4612ab3a..c5ee9987 100644 --- a/src/main/java/org/bukkit/configuration/serialization/SerializableAs.java +++ b/src/main/java/org/bukkit/configuration/serialization/SerializableAs.java @@ -6,15 +6,16 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Represents an "alias" that a {@link ConfigurationSerializable} may be stored as. - * If this is not present on a {@link ConfigurationSerializable} class, it will use the - * fully qualified name of the class. + * Represents an "alias" that a {@link ConfigurationSerializable} may be + * stored as. + * If this is not present on a {@link ConfigurationSerializable} class, it + * will use the fully qualified name of the class. * <p> - * This value will be stored in the configuration so that the configuration deserialization - * can determine what type it is. + * This value will be stored in the configuration so that the configuration + * deserialization can determine what type it is. * <p> - * Using this annotation on any other class than a {@link ConfigurationSerializable} will - * have no effect. + * Using this annotation on any other class than a {@link + * ConfigurationSerializable} will have no effect. * * @see ConfigurationSerialization#registerClass(Class, String) */ @@ -24,8 +25,8 @@ public @interface SerializableAs { /** * This is the name your class will be stored and retrieved as. * <p> - * This name MUST be unique. We recommend using names such as "MyPluginThing" instead of - * "Thing". + * This name MUST be unique. We recommend using names such as + * "MyPluginThing" instead of "Thing". * * @return Name to serialize the class as. */ diff --git a/src/main/java/org/bukkit/conversations/BooleanPrompt.java b/src/main/java/org/bukkit/conversations/BooleanPrompt.java index 6abb3547..3f2c97f4 100644 --- a/src/main/java/org/bukkit/conversations/BooleanPrompt.java +++ b/src/main/java/org/bukkit/conversations/BooleanPrompt.java @@ -4,7 +4,8 @@ import org.apache.commons.lang.ArrayUtils; import org.apache.commons.lang.BooleanUtils; /** - * BooleanPrompt is the base class for any prompt that requires a boolean response from the user. + * BooleanPrompt is the base class for any prompt that requires a boolean + * response from the user. */ public abstract class BooleanPrompt extends ValidatingPrompt{ @@ -24,7 +25,8 @@ public abstract class BooleanPrompt extends ValidatingPrompt{ } /** - * Override this method to perform some action with the user's boolean response. + * Override this method to perform some action with the user's boolean + * response. * * @param context Context information about the conversation. * @param input The user's boolean response. diff --git a/src/main/java/org/bukkit/conversations/Conversable.java b/src/main/java/org/bukkit/conversations/Conversable.java index 52b80b6d..55674b53 100644 --- a/src/main/java/org/bukkit/conversations/Conversable.java +++ b/src/main/java/org/bukkit/conversations/Conversable.java @@ -3,20 +3,22 @@ package org.bukkit.conversations; import org.bukkit.command.CommandSender; /** - * The Conversable interface is used to indicate objects that can have conversations. + * The Conversable interface is used to indicate objects that can have + * conversations. */ public interface Conversable { /** - * Tests to see of a Conversable object is actively engaged in a conversation. + * Tests to see of a Conversable object is actively engaged in a + * conversation. * * @return True if a conversation is in progress */ public boolean isConversing(); /** - * Accepts input into the active conversation. If no conversation is in progress, - * this method does nothing. + * Accepts input into the active conversation. If no conversation is in + * progress, this method does nothing. * * @param input The input message into the conversation */ @@ -26,7 +28,8 @@ public interface Conversable { * Enters into a dialog with a Conversation object. * * @param conversation The conversation to begin - * @return True if the conversation should proceed, false if it has been enqueued + * @return True if the conversation should proceed, false if it has been + * enqueued */ public boolean beginConversation(Conversation conversation); diff --git a/src/main/java/org/bukkit/conversations/Conversation.java b/src/main/java/org/bukkit/conversations/Conversation.java index a30745fe..d4c1f6d3 100644 --- a/src/main/java/org/bukkit/conversations/Conversation.java +++ b/src/main/java/org/bukkit/conversations/Conversation.java @@ -8,23 +8,29 @@ import java.util.List; import java.util.Map; /** - * The Conversation class is responsible for tracking the current state of a conversation, displaying prompts to - * the user, and dispatching the user's response to the appropriate place. Conversation objects are not typically - * instantiated directly. Instead a {@link ConversationFactory} is used to construct identical conversations on demand. + * The Conversation class is responsible for tracking the current state of a + * conversation, displaying prompts to the user, and dispatching the user's + * response to the appropriate place. Conversation objects are not typically + * instantiated directly. Instead a {@link ConversationFactory} is used to + * construct identical conversations on demand. * <p> - * Conversation flow consists of a directed graph of {@link Prompt} objects. Each time a prompt gets input from the - * user, it must return the next prompt in the graph. Since each Prompt chooses the next Prompt, complex conversation - * trees can be implemented where the nature of the player's response directs the flow of the conversation. + * Conversation flow consists of a directed graph of {@link Prompt} objects. + * Each time a prompt gets input from the user, it must return the next prompt + * in the graph. Since each Prompt chooses the next Prompt, complex + * conversation trees can be implemented where the nature of the player's + * response directs the flow of the conversation. * <p> - * Each conversation has a {@link ConversationPrefix} that prepends all output from the conversation to the player. - * The ConversationPrefix can be used to display the plugin name or conversation status as the conversation evolves. + * Each conversation has a {@link ConversationPrefix} that prepends all output + * from the conversation to the player. The ConversationPrefix can be used to + * display the plugin name or conversation status as the conversation evolves. * <p> - * Each conversation has a timeout measured in the number of inactive seconds to wait before abandoning the conversation. - * If the inactivity timeout is reached, the conversation is abandoned and the user's incoming and outgoing chat is - * returned to normal. + * Each conversation has a timeout measured in the number of inactive seconds + * to wait before abandoning the conversation. If the inactivity timeout is + * reached, the conversation is abandoned and the user's incoming and outgoing + * chat is returned to normal. * <p> - * You should not construct a conversation manually. Instead, use the {@link ConversationFactory} for access to all - * available options. + * You should not construct a conversation manually. Instead, use the {@link + * ConversationFactory} for access to all available options. */ public class Conversation { @@ -55,7 +61,8 @@ public class Conversation { * @param plugin The plugin that owns this conversation. * @param forWhom The entity for whom this conversation is mediating. * @param firstPrompt The first prompt in the conversation graph. - * @param initialSessionData Any initial values to put in the conversation context sessionData map. + * @param initialSessionData Any initial values to put in the conversation + * context sessionData map. */ public Conversation(Plugin plugin, Conversable forWhom, Prompt firstPrompt, Map<Object, Object> initialSessionData) { this.firstPrompt = firstPrompt; @@ -77,8 +84,9 @@ public class Conversation { } /** - * Gets the modality of this conversation. If a conversation is modal, all messages directed to the player - * are suppressed for the duration of the conversation. + * Gets the modality of this conversation. If a conversation is modal, all + * messages directed to the player are suppressed for the duration of the + * conversation. * * @return The conversation modality. */ @@ -87,8 +95,9 @@ public class Conversation { } /** - * Sets the modality of this conversation. If a conversation is modal, all messages directed to the player - * are suppressed for the duration of the conversation. + * Sets the modality of this conversation. If a conversation is modal, + * all messages directed to the player are suppressed for the duration of + * the conversation. * * @param modal The new conversation modality. */ @@ -97,8 +106,9 @@ public class Conversation { } /** - * Gets the status of local echo for this conversation. If local echo is enabled, any text submitted to a conversation - * gets echoed back into the submitter's chat window. + * Gets the status of local echo for this conversation. If local echo is + * enabled, any text submitted to a conversation gets echoed back into the + * submitter's chat window. * * @return The status of local echo. */ @@ -107,8 +117,9 @@ public class Conversation { } /** - * Sets the status of local echo for this conversation. If local echo is enabled, any text submitted to a conversation - * gets echoed back into the submitter's chat window. + * Sets the status of local echo for this conversation. If local echo is + * enabled, any text submitted to a conversation gets echoed back into the + * submitter's chat window. * * @param localEchoEnabled The status of local echo. */ @@ -117,7 +128,8 @@ public class Conversation { } /** - * Gets the {@link ConversationPrefix} that prepends all output from this conversation. + * Gets the {@link ConversationPrefix} that prepends all output from this + * conversation. * * @return The ConversationPrefix in use. */ @@ -126,7 +138,8 @@ public class Conversation { } /** - * Sets the {@link ConversationPrefix} that prepends all output from this conversation. + * Sets the {@link ConversationPrefix} that prepends all output from this + * conversation. * * @param prefix The ConversationPrefix to use. */ @@ -163,7 +176,8 @@ public class Conversation { } /** - * Displays the first prompt of this conversation and begins redirecting the user's chat responses. + * Displays the first prompt of this conversation and begins redirecting + * the user's chat responses. */ public void begin() { if (currentPrompt == null) { @@ -175,6 +189,7 @@ public class Conversation { /** * Returns Returns the current state of the conversation. + * * @return The current state of the conversation. */ public ConversationState getState() { @@ -188,8 +203,9 @@ public class Conversation { } /** - * Passes player input into the current prompt. The next prompt (as determined by the current prompt) is then - * displayed to the user. + * Passes player input into the current prompt. The next prompt (as + * determined by the current prompt) is then displayed to the user. + * * @param input The user's chat text. */ public void acceptInput(String input) { @@ -216,6 +232,7 @@ public class Conversation { /** * Adds a {@link ConversationAbandonedListener}. + * * @param listener The listener to add. */ public synchronized void addConversationAbandonedListener(ConversationAbandonedListener listener) { @@ -224,6 +241,7 @@ public class Conversation { /** * Removes a {@link ConversationAbandonedListener}. + * * @param listener The listener to remove. */ public synchronized void removeConversationAbandonedListener(ConversationAbandonedListener listener) { @@ -231,14 +249,17 @@ public class Conversation { } /** - * Abandons and resets the current conversation. Restores the user's normal chat behavior. + * Abandons and resets the current conversation. Restores the user's + * normal chat behavior. */ public void abandon() { abandon(new ConversationAbandonedEvent(this, new ManuallyAbandonedConversationCanceller())); } /** - * Abandons and resets the current conversation. Restores the user's normal chat behavior. + * Abandons and resets the current conversation. Restores the user's + * normal chat behavior. + * * @param details Details about why the conversation was abandoned */ public synchronized void abandon(ConversationAbandonedEvent details) { @@ -253,7 +274,8 @@ public class Conversation { } /** - * Displays the next user prompt and abandons the conversation if the next prompt is null. + * Displays the next user prompt and abandons the conversation if the next + * prompt is null. */ public void outputNextPrompt() { if (currentPrompt == null) { diff --git a/src/main/java/org/bukkit/conversations/ConversationAbandonedEvent.java b/src/main/java/org/bukkit/conversations/ConversationAbandonedEvent.java index b3e74852..63c4a2aa 100644 --- a/src/main/java/org/bukkit/conversations/ConversationAbandonedEvent.java +++ b/src/main/java/org/bukkit/conversations/ConversationAbandonedEvent.java @@ -3,7 +3,8 @@ package org.bukkit.conversations; import java.util.EventObject; /** - * ConversationAbandonedEvent contains information about an abandoned conversation. + * ConversationAbandonedEvent contains information about an abandoned + * conversation. */ public class ConversationAbandonedEvent extends EventObject { @@ -39,11 +40,12 @@ public class ConversationAbandonedEvent extends EventObject { } /** - * Indicates how the conversation was abandoned - naturally as part of the prompt chain or prematurely via a - * {@link ConversationCanceller}. + * Indicates how the conversation was abandoned - naturally as part of the + * prompt chain or prematurely via a {@link ConversationCanceller}. * - * @return True if the conversation is abandoned gracefully by a {@link Prompt} returning null - * or the next prompt. False of the conversations is abandoned prematurely by a ConversationCanceller. + * @return True if the conversation is abandoned gracefully by a {@link + * Prompt} returning null or the next prompt. False of the + * conversations is abandoned prematurely by a ConversationCanceller. */ public boolean gracefulExit() { return canceller == null; diff --git a/src/main/java/org/bukkit/conversations/ConversationAbandonedListener.java b/src/main/java/org/bukkit/conversations/ConversationAbandonedListener.java index b026a005..dc046b1f 100644 --- a/src/main/java/org/bukkit/conversations/ConversationAbandonedListener.java +++ b/src/main/java/org/bukkit/conversations/ConversationAbandonedListener.java @@ -8,7 +8,8 @@ public interface ConversationAbandonedListener extends EventListener { /** * Called whenever a {@link Conversation} is abandoned. * - * @param abandonedEvent Contains details about the abandoned conversation. + * @param abandonedEvent Contains details about the abandoned + * conversation. */ public void conversationAbandoned(ConversationAbandonedEvent abandonedEvent); } diff --git a/src/main/java/org/bukkit/conversations/ConversationCanceller.java b/src/main/java/org/bukkit/conversations/ConversationCanceller.java index 77971cdd..db43bb16 100644 --- a/src/main/java/org/bukkit/conversations/ConversationCanceller.java +++ b/src/main/java/org/bukkit/conversations/ConversationCanceller.java @@ -1,8 +1,8 @@ package org.bukkit.conversations; /** - * A ConversationCanceller is a class that cancels an active {@link Conversation}. A Conversation can have more - * than one ConversationCanceller. + * A ConversationCanceller is a class that cancels an active {@link + * Conversation}. A Conversation can have more than one ConversationCanceller. */ public interface ConversationCanceller extends Cloneable { @@ -23,7 +23,8 @@ public interface ConversationCanceller extends Cloneable { public boolean cancelBasedOnInput(ConversationContext context, String input); /** - * Allows the {@link ConversationFactory} to duplicate this ConversationCanceller when creating a new {@link Conversation}. + * Allows the {@link ConversationFactory} to duplicate this + * ConversationCanceller when creating a new {@link Conversation}. * <p> * Implementing this method should reset any internal object state. * diff --git a/src/main/java/org/bukkit/conversations/ConversationContext.java b/src/main/java/org/bukkit/conversations/ConversationContext.java index 7a5b5edc..4f33ff46 100644 --- a/src/main/java/org/bukkit/conversations/ConversationContext.java +++ b/src/main/java/org/bukkit/conversations/ConversationContext.java @@ -5,8 +5,9 @@ import org.bukkit.plugin.Plugin; import java.util.Map; /** - * A ConversationContext provides continuity between nodes in the prompt graph by giving the developer access to the - * subject of the conversation and a generic map for storing values that are shared between all {@link Prompt} + * A ConversationContext provides continuity between nodes in the prompt graph + * by giving the developer access to the subject of the conversation and a + * generic map for storing values that are shared between all {@link Prompt} * invocations. */ public class ConversationContext { @@ -17,7 +18,8 @@ public class ConversationContext { /** * @param plugin The owning plugin. * @param forWhom The subject of the conversation. - * @param initialSessionData Any initial values to put in the sessionData map. + * @param initialSessionData Any initial values to put in the sessionData + * map. */ public ConversationContext(Plugin plugin, Conversable forWhom, Map<Object, Object> initialSessionData) { this.plugin = plugin; @@ -44,8 +46,9 @@ public class ConversationContext { } /** - * Gets session data shared between all {@link Prompt} invocations. Use this as a way - * to pass data through each Prompt as the conversation develops. + * Gets session data shared between all {@link Prompt} invocations. Use + * this as a way to pass data through each Prompt as the conversation + * develops. * * @param key The session data key. * @return The requested session data. @@ -55,8 +58,9 @@ public class ConversationContext { } /** - * Sets session data shared between all {@link Prompt} invocations. Use this as a way to pass - * data through each prompt as the conversation develops. + * Sets session data shared between all {@link Prompt} invocations. Use + * this as a way to pass data through each prompt as the conversation + * develops. * * @param key The session data key. * @param value The session data value. diff --git a/src/main/java/org/bukkit/conversations/ConversationFactory.java b/src/main/java/org/bukkit/conversations/ConversationFactory.java index 59104d74..e7cbd52c 100644 --- a/src/main/java/org/bukkit/conversations/ConversationFactory.java +++ b/src/main/java/org/bukkit/conversations/ConversationFactory.java @@ -9,11 +9,14 @@ import java.util.List; import java.util.Map; /** - * A ConversationFactory is responsible for creating a {@link Conversation} from a predefined template. A ConversationFactory - * is typically created when a plugin is instantiated and builds a Conversation each time a user initiates a conversation - * with the plugin. Each Conversation maintains its own state and calls back as needed into the plugin. + * A ConversationFactory is responsible for creating a {@link Conversation} + * from a predefined template. A ConversationFactory is typically created when + * a plugin is instantiated and builds a Conversation each time a user + * initiates a conversation with the plugin. Each Conversation maintains its + * own state and calls back as needed into the plugin. * <p> - * The ConversationFactory implements a fluid API, allowing parameters to be set as an extension to the constructor. + * The ConversationFactory implements a fluid API, allowing parameters to be + * set as an extension to the constructor. */ public class ConversationFactory { @@ -46,8 +49,9 @@ public class ConversationFactory { } /** - * Sets the modality of all {@link Conversation}s created by this factory. If a conversation is modal, all messages - * directed to the player are suppressed for the duration of the conversation. + * Sets the modality of all {@link Conversation}s created by this factory. + * If a conversation is modal, all messages directed to the player are + * suppressed for the duration of the conversation. * <p> * The default is True. * @@ -61,8 +65,9 @@ public class ConversationFactory { } /** - * Sets the local echo status for all {@link Conversation}s created by this factory. If local echo is enabled, - * any text submitted to a conversation gets echoed back into the submitter's chat window. + * Sets the local echo status for all {@link Conversation}s created by + * this factory. If local echo is enabled, any text submitted to a + * conversation gets echoed back into the submitter's chat window. * * @param localEchoEnabled The status of local echo. * @return This object. @@ -73,7 +78,8 @@ public class ConversationFactory { } /** - * Sets the {@link ConversationPrefix} that prepends all output from all generated conversations. + * Sets the {@link ConversationPrefix} that prepends all output from all + * generated conversations. * <p> * The default is a {@link NullConversationPrefix}; * @@ -86,7 +92,8 @@ public class ConversationFactory { } /** - * Sets the number of inactive seconds to wait before automatically abandoning all generated conversations. + * Sets the number of inactive seconds to wait before automatically + * abandoning all generated conversations. * <p> * The default is 600 seconds (5 minutes). * @@ -111,9 +118,11 @@ public class ConversationFactory { } /** - * Sets any initial data with which to populate the conversation context sessionData map. + * Sets any initial data with which to populate the conversation context + * sessionData map. * - * @param initialSessionData The conversation context's initial sessionData. + * @param initialSessionData The conversation context's initial + * sessionData. * @return This object. */ public ConversationFactory withInitialSessionData(Map<Object, Object> initialSessionData) { @@ -122,7 +131,8 @@ public class ConversationFactory { } /** - * Sets the player input that, when received, will immediately terminate the conversation. + * Sets the player input that, when received, will immediately terminate + * the conversation. * * @param escapeSequence Input to terminate the conversation. * @return This object. @@ -144,9 +154,11 @@ public class ConversationFactory { } /** - * Prevents this factory from creating a conversation for non-player {@link Conversable} objects. + * Prevents this factory from creating a conversation for non-player + * {@link Conversable} objects. * - * @param playerOnlyMessage The message to return to a non-play in lieu of starting a conversation. + * @param playerOnlyMessage The message to return to a non-play in lieu of + * starting a conversation. * @return This object. */ public ConversationFactory thatExcludesNonPlayersWithMessage(String playerOnlyMessage) { @@ -155,7 +167,8 @@ public class ConversationFactory { } /** - * Adds a {@link ConversationAbandonedListener} to all conversations constructed by this factory. + * Adds a {@link ConversationAbandonedListener} to all conversations + * constructed by this factory. * * @param listener The listener to add. * @return This object. @@ -166,7 +179,8 @@ public class ConversationFactory { } /** - * Constructs a {@link Conversation} in accordance with the defaults set for this factory. + * Constructs a {@link Conversation} in accordance with the defaults set + * for this factory. * * @param forWhom The entity for whom the new conversation is mediating. * @return A new conversation. diff --git a/src/main/java/org/bukkit/conversations/ConversationPrefix.java b/src/main/java/org/bukkit/conversations/ConversationPrefix.java index 448638f5..9889f17e 100644 --- a/src/main/java/org/bukkit/conversations/ConversationPrefix.java +++ b/src/main/java/org/bukkit/conversations/ConversationPrefix.java @@ -3,8 +3,9 @@ package org.bukkit.conversations; import org.bukkit.command.CommandSender; /** - * A ConversationPrefix implementation prepends all output from the conversation to the player. - * The ConversationPrefix can be used to display the plugin name or conversation status as the conversation evolves. + * A ConversationPrefix implementation prepends all output from the + * conversation to the player. The ConversationPrefix can be used to display + * the plugin name or conversation status as the conversation evolves. */ public interface ConversationPrefix { diff --git a/src/main/java/org/bukkit/conversations/ExactMatchConversationCanceller.java b/src/main/java/org/bukkit/conversations/ExactMatchConversationCanceller.java index 6f38bebf..327b9d99 100644 --- a/src/main/java/org/bukkit/conversations/ExactMatchConversationCanceller.java +++ b/src/main/java/org/bukkit/conversations/ExactMatchConversationCanceller.java @@ -1,7 +1,8 @@ package org.bukkit.conversations; /** - * An ExactMatchConversationCanceller cancels a conversation if the user enters an exact input string + * An ExactMatchConversationCanceller cancels a conversation if the user + * enters an exact input string */ public class ExactMatchConversationCanceller implements ConversationCanceller { private String escapeSequence; @@ -9,7 +10,8 @@ public class ExactMatchConversationCanceller implements ConversationCanceller { /** * Builds an ExactMatchConversationCanceller. * - * @param escapeSequence The string that, if entered by the user, will cancel the conversation. + * @param escapeSequence The string that, if entered by the user, will + * cancel the conversation. */ public ExactMatchConversationCanceller(String escapeSequence) { this.escapeSequence = escapeSequence; diff --git a/src/main/java/org/bukkit/conversations/FixedSetPrompt.java b/src/main/java/org/bukkit/conversations/FixedSetPrompt.java index 6cf71d66..b867c116 100644 --- a/src/main/java/org/bukkit/conversations/FixedSetPrompt.java +++ b/src/main/java/org/bukkit/conversations/FixedSetPrompt.java @@ -6,7 +6,8 @@ import java.util.Arrays; import java.util.List; /** - * FixedSetPrompt is the base class for any prompt that requires a fixed set response from the user. + * FixedSetPrompt is the base class for any prompt that requires a fixed set + * response from the user. */ public abstract class FixedSetPrompt extends ValidatingPrompt { @@ -14,9 +15,11 @@ public abstract class FixedSetPrompt extends ValidatingPrompt { /** * Creates a FixedSetPrompt from a set of strings. + * <p> * foo = new FixedSetPrompt("bar", "cheese", "panda"); * - * @param fixedSet A fixed set of strings, one of which the user must type. + * @param fixedSet A fixed set of strings, one of which the user must + * type. */ public FixedSetPrompt(String... fixedSet) { super(); @@ -31,9 +34,11 @@ public abstract class FixedSetPrompt extends ValidatingPrompt { } /** - * Utility function to create a formatted string containing all the options declared in the constructor. + * Utility function to create a formatted string containing all the + * options declared in the constructor. * - * @return the options formatted like "[bar, cheese, panda]" if bar, cheese, and panda were the options used + * @return the options formatted like "[bar, cheese, panda]" if bar, + * cheese, and panda were the options used */ protected String formatFixedSet() { return "[" + StringUtils.join(fixedSet, ", ") + "]"; diff --git a/src/main/java/org/bukkit/conversations/InactivityConversationCanceller.java b/src/main/java/org/bukkit/conversations/InactivityConversationCanceller.java index a6440e93..760a518e 100644 --- a/src/main/java/org/bukkit/conversations/InactivityConversationCanceller.java +++ b/src/main/java/org/bukkit/conversations/InactivityConversationCanceller.java @@ -4,7 +4,8 @@ import org.bukkit.Server; import org.bukkit.plugin.Plugin; /** - * An InactivityConversationCanceller will cancel a {@link Conversation} after a period of inactivity by the user. + * An InactivityConversationCanceller will cancel a {@link Conversation} after + * a period of inactivity by the user. */ public class InactivityConversationCanceller implements ConversationCanceller { protected Plugin plugin; @@ -66,8 +67,9 @@ public class InactivityConversationCanceller implements ConversationCanceller { } /** - * Subclasses of InactivityConversationCanceller can override this method to take additional actions when the - * inactivity timer abandons the conversation. + * Subclasses of InactivityConversationCanceller can override this method + * to take additional actions when the inactivity timer abandons the + * conversation. * * @param conversation The conversation being abandoned. */ diff --git a/src/main/java/org/bukkit/conversations/ManuallyAbandonedConversationCanceller.java b/src/main/java/org/bukkit/conversations/ManuallyAbandonedConversationCanceller.java index 6d7bd8fb..3e80de1f 100644 --- a/src/main/java/org/bukkit/conversations/ManuallyAbandonedConversationCanceller.java +++ b/src/main/java/org/bukkit/conversations/ManuallyAbandonedConversationCanceller.java @@ -1,8 +1,9 @@ package org.bukkit.conversations; /** - * The ManuallyAbandonedConversationCanceller is only used as part of a {@link ConversationAbandonedEvent} to indicate - * that the conversation was manually abandoned by programatically calling the abandon() method on it. + * The ManuallyAbandonedConversationCanceller is only used as part of a {@link + * ConversationAbandonedEvent} to indicate that the conversation was manually + * abandoned by programmatically calling the abandon() method on it. */ public class ManuallyAbandonedConversationCanceller implements ConversationCanceller{ public void setConversation(Conversation conversation) { diff --git a/src/main/java/org/bukkit/conversations/MessagePrompt.java b/src/main/java/org/bukkit/conversations/MessagePrompt.java index d9478bb8..fa1775a4 100644 --- a/src/main/java/org/bukkit/conversations/MessagePrompt.java +++ b/src/main/java/org/bukkit/conversations/MessagePrompt.java @@ -1,7 +1,8 @@ package org.bukkit.conversations; /** - * MessagePrompt is the base class for any prompt that only displays a message to the user and requires no input. + * MessagePrompt is the base class for any prompt that only displays a message + * to the user and requires no input. */ public abstract class MessagePrompt implements Prompt{ @@ -20,7 +21,8 @@ public abstract class MessagePrompt implements Prompt{ } /** - * Accepts and ignores any user input, returning the next prompt in the prompt graph instead. + * Accepts and ignores any user input, returning the next prompt in the + * prompt graph instead. * * @param context Context information about the conversation. * @param input Ignored. diff --git a/src/main/java/org/bukkit/conversations/NullConversationPrefix.java b/src/main/java/org/bukkit/conversations/NullConversationPrefix.java index ab6aa71a..7d8a7d85 100644 --- a/src/main/java/org/bukkit/conversations/NullConversationPrefix.java +++ b/src/main/java/org/bukkit/conversations/NullConversationPrefix.java @@ -3,8 +3,8 @@ package org.bukkit.conversations; import org.bukkit.command.CommandSender; /** - * NullConversationPrefix is a {@link ConversationPrefix} implementation that displays nothing in front of - * conversation output. + * NullConversationPrefix is a {@link ConversationPrefix} implementation that + * displays nothing in front of conversation output. */ public class NullConversationPrefix implements ConversationPrefix{ diff --git a/src/main/java/org/bukkit/conversations/NumericPrompt.java b/src/main/java/org/bukkit/conversations/NumericPrompt.java index a57fb07d..f0fdea1c 100644 --- a/src/main/java/org/bukkit/conversations/NumericPrompt.java +++ b/src/main/java/org/bukkit/conversations/NumericPrompt.java @@ -3,7 +3,8 @@ package org.bukkit.conversations; import org.apache.commons.lang.math.NumberUtils; /** - * NumericPrompt is the base class for any prompt that requires a {@link Number} response from the user. + * NumericPrompt is the base class for any prompt that requires a {@link + * Number} response from the user. */ public abstract class NumericPrompt extends ValidatingPrompt{ public NumericPrompt() { @@ -16,8 +17,8 @@ public abstract class NumericPrompt extends ValidatingPrompt{ } /** - * Override this method to do further validation on the numeric player input after the input has been determined - * to actually be a number. + * Override this method to do further validation on the numeric player + * input after the input has been determined to actually be a number. * * @param context Context information about the conversation. * @param input The number the player provided. @@ -38,7 +39,8 @@ public abstract class NumericPrompt extends ValidatingPrompt{ } /** - * Override this method to perform some action with the user's integer response. + * Override this method to perform some action with the user's integer + * response. * * @param context Context information about the conversation. * @param input The user's response as a {@link Number}. @@ -56,7 +58,8 @@ public abstract class NumericPrompt extends ValidatingPrompt{ } /** - * Optionally override this method to display an additional message if the user enters an invalid number. + * Optionally override this method to display an additional message if the + * user enters an invalid number. * * @param context Context information about the conversation. * @param invalidInput The invalid input provided by the user. @@ -67,7 +70,8 @@ public abstract class NumericPrompt extends ValidatingPrompt{ } /** - * Optionally override this method to display an additional message if the user enters an invalid numeric input. + * Optionally override this method to display an additional message if the + * user enters an invalid numeric input. * * @param context Context information about the conversation. * @param invalidInput The invalid input provided by the user. diff --git a/src/main/java/org/bukkit/conversations/PlayerNamePrompt.java b/src/main/java/org/bukkit/conversations/PlayerNamePrompt.java index 5fa63446..feeb7155 100644 --- a/src/main/java/org/bukkit/conversations/PlayerNamePrompt.java +++ b/src/main/java/org/bukkit/conversations/PlayerNamePrompt.java @@ -4,7 +4,8 @@ import org.bukkit.entity.Player; import org.bukkit.plugin.Plugin; /** - * PlayerNamePrompt is the base class for any prompt that requires the player to enter another player's name. + * PlayerNamePrompt is the base class for any prompt that requires the player + * to enter another player's name. */ public abstract class PlayerNamePrompt extends ValidatingPrompt{ private Plugin plugin; @@ -26,7 +27,8 @@ public abstract class PlayerNamePrompt extends ValidatingPrompt{ } /** - * Override this method to perform some action with the user's player name response. + * Override this method to perform some action with the user's player name + * response. * * @param context Context information about the conversation. * @param input The user's player name response. diff --git a/src/main/java/org/bukkit/conversations/PluginNameConversationPrefix.java b/src/main/java/org/bukkit/conversations/PluginNameConversationPrefix.java index 2f06809e..2290979c 100644 --- a/src/main/java/org/bukkit/conversations/PluginNameConversationPrefix.java +++ b/src/main/java/org/bukkit/conversations/PluginNameConversationPrefix.java @@ -5,8 +5,8 @@ import org.bukkit.command.CommandSender; import org.bukkit.plugin.Plugin; /** - * PluginNameConversationPrefix is a {@link ConversationPrefix} implementation that displays the plugin name in front of - * conversation output. + * PluginNameConversationPrefix is a {@link ConversationPrefix} implementation + * that displays the plugin name in front of conversation output. */ public class PluginNameConversationPrefix implements ConversationPrefix { diff --git a/src/main/java/org/bukkit/conversations/Prompt.java b/src/main/java/org/bukkit/conversations/Prompt.java index 67800ccd..7519c843 100644 --- a/src/main/java/org/bukkit/conversations/Prompt.java +++ b/src/main/java/org/bukkit/conversations/Prompt.java @@ -1,9 +1,11 @@ package org.bukkit.conversations; /** - * A Prompt is the main constituent of a {@link Conversation}. Each prompt displays text to the user and optionally - * waits for a user's response. Prompts are chained together into a directed graph that represents the conversation - * flow. To halt a conversation, END_OF_CONVERSATION is returned in liu of another Prompt object. + * A Prompt is the main constituent of a {@link Conversation}. Each prompt + * displays text to the user and optionally waits for a user's response. + * Prompts are chained together into a directed graph that represents the + * conversation flow. To halt a conversation, END_OF_CONVERSATION is returned + * in liu of another Prompt object. */ public interface Prompt extends Cloneable { @@ -13,7 +15,8 @@ public interface Prompt extends Cloneable { static final Prompt END_OF_CONVERSATION = null; /** - * Gets the text to display to the user when this prompt is first presented. + * Gets the text to display to the user when this prompt is first + * presented. * * @param context Context information about the conversation. * @return The text to display. @@ -21,15 +24,18 @@ public interface Prompt extends Cloneable { String getPromptText(ConversationContext context); /** - * Checks to see if this prompt implementation should wait for user input or immediately display the next prompt. + * Checks to see if this prompt implementation should wait for user input + * or immediately display the next prompt. * * @param context Context information about the conversation. - * @return If true, the {@link Conversation} will wait for input before continuing. + * @return If true, the {@link Conversation} will wait for input before + * continuing. */ boolean blocksForInput(ConversationContext context); /** - * Accepts and processes input from the user. Using the input, the next Prompt in the prompt graph is returned. + * Accepts and processes input from the user. Using the input, the next + * Prompt in the prompt graph is returned. * * @param context Context information about the conversation. * @param input The input text from the user. diff --git a/src/main/java/org/bukkit/conversations/RegexPrompt.java b/src/main/java/org/bukkit/conversations/RegexPrompt.java index 437f9ca4..a3c7d1f1 100644 --- a/src/main/java/org/bukkit/conversations/RegexPrompt.java +++ b/src/main/java/org/bukkit/conversations/RegexPrompt.java @@ -3,7 +3,8 @@ package org.bukkit.conversations; import java.util.regex.Pattern; /** - * RegexPrompt is the base class for any prompt that requires an input validated by a regular expression. + * RegexPrompt is the base class for any prompt that requires an input + * validated by a regular expression. */ public abstract class RegexPrompt extends ValidatingPrompt { diff --git a/src/main/java/org/bukkit/conversations/StringPrompt.java b/src/main/java/org/bukkit/conversations/StringPrompt.java index 0098b11e..29344595 100644 --- a/src/main/java/org/bukkit/conversations/StringPrompt.java +++ b/src/main/java/org/bukkit/conversations/StringPrompt.java @@ -1,7 +1,8 @@ package org.bukkit.conversations; /** - * StringPrompt is the base class for any prompt that accepts an arbitrary string from the user. + * StringPrompt is the base class for any prompt that accepts an arbitrary + * string from the user. */ public abstract class StringPrompt implements Prompt{ diff --git a/src/main/java/org/bukkit/conversations/ValidatingPrompt.java b/src/main/java/org/bukkit/conversations/ValidatingPrompt.java index 47e57822..f41adb4a 100644 --- a/src/main/java/org/bukkit/conversations/ValidatingPrompt.java +++ b/src/main/java/org/bukkit/conversations/ValidatingPrompt.java @@ -3,8 +3,9 @@ package org.bukkit.conversations; import org.bukkit.ChatColor; /** - * ValidatingPrompt is the base class for any prompt that requires validation. ValidatingPrompt will keep replaying - * the prompt text until the user enters a valid response. + * ValidatingPrompt is the base class for any prompt that requires validation. + * ValidatingPrompt will keep replaying the prompt text until the user enters + * a valid response. */ public abstract class ValidatingPrompt implements Prompt { public ValidatingPrompt() { @@ -12,8 +13,9 @@ public abstract class ValidatingPrompt implements Prompt { } /** - * Accepts and processes input from the user and validates it. If validation fails, this prompt is returned for - * re-execution, otherwise the next Prompt in the prompt graph is returned. + * Accepts and processes input from the user and validates it. If + * validation fails, this prompt is returned for re-execution, otherwise + * the next Prompt in the prompt graph is returned. * * @param context Context information about the conversation. * @param input The input text from the user. @@ -52,8 +54,9 @@ public abstract class ValidatingPrompt implements Prompt { protected abstract boolean isInputValid(ConversationContext context, String input); /** - * Override this method to accept and processes the validated input from the user. Using the input, the next Prompt - * in the prompt graph should be returned. + * Override this method to accept and processes the validated input from + * the user. Using the input, the next Prompt in the prompt graph should + * be returned. * * @param context Context information about the conversation. * @param input The validated input text from the user. @@ -62,7 +65,8 @@ public abstract class ValidatingPrompt implements Prompt { protected abstract Prompt acceptValidatedInput(ConversationContext context, String input); /** - * Optionally override this method to display an additional message if the user enters an invalid input. + * Optionally override this method to display an additional message if the + * user enters an invalid input. * * @param context Context information about the conversation. * @param invalidInput The invalid input provided by the user. diff --git a/src/main/java/org/bukkit/enchantments/Enchantment.java b/src/main/java/org/bukkit/enchantments/Enchantment.java index 61a8bca6..e038412d 100644 --- a/src/main/java/org/bukkit/enchantments/Enchantment.java +++ b/src/main/java/org/bukkit/enchantments/Enchantment.java @@ -86,7 +86,8 @@ public abstract class Enchantment { public static final Enchantment DIG_SPEED = new EnchantmentWrapper(32); /** - * Allows blocks to drop themselves instead of fragments (for example, stone instead of cobblestone) + * Allows blocks to drop themselves instead of fragments (for example, + * stone instead of cobblestone) */ public static final Enchantment SILK_TOUCH = new EnchantmentWrapper(33); @@ -187,8 +188,11 @@ public abstract class Enchantment { public abstract boolean conflictsWith(Enchantment other); /** - * Checks if this Enchantment may be applied to the given {@link ItemStack}. - * This does not check if it conflicts with any enchantments already applied to the item. + * Checks if this Enchantment may be applied to the given {@link + * ItemStack}. + * <p> + * This does not check if it conflicts with any enchantments already + * applied to the item. * * @param item Item to test * @return True if the enchantment may be applied, otherwise False diff --git a/src/main/java/org/bukkit/enchantments/EnchantmentTarget.java b/src/main/java/org/bukkit/enchantments/EnchantmentTarget.java index 6578b36a..d9b98ed6 100644 --- a/src/main/java/org/bukkit/enchantments/EnchantmentTarget.java +++ b/src/main/java/org/bukkit/enchantments/EnchantmentTarget.java @@ -101,7 +101,8 @@ public enum EnchantmentTarget { }, /** - * Allows the Enchantment to be placed on tools (spades, pickaxe, hoes, axes) + * Allows the Enchantment to be placed on tools (spades, pickaxe, hoes, + * axes) */ TOOL { @Override diff --git a/src/main/java/org/bukkit/entity/Ageable.java b/src/main/java/org/bukkit/entity/Ageable.java index 0e7472a1..e9fccb29 100644 --- a/src/main/java/org/bukkit/entity/Ageable.java +++ b/src/main/java/org/bukkit/entity/Ageable.java @@ -19,7 +19,8 @@ public interface Ageable extends Creature { public void setAge(int age); /** - * Lock the age of the animal, setting this will prevent the animal from maturing or getting ready for mating. + * Lock the age of the animal, setting this will prevent the animal from + * maturing or getting ready for mating. * * @param lock new lock */ @@ -57,7 +58,8 @@ public interface Ageable extends Creature { public boolean canBreed(); /** - * Set breedability of the animal, if the animal is a baby and set to breed it will instantly grow up. + * Set breedability of the animal, if the animal is a baby and set to + * breed it will instantly grow up. * * @param breed breedability of the animal */ diff --git a/src/main/java/org/bukkit/entity/Boat.java b/src/main/java/org/bukkit/entity/Boat.java index c363a38f..ed2d1788 100644 --- a/src/main/java/org/bukkit/entity/Boat.java +++ b/src/main/java/org/bukkit/entity/Boat.java @@ -6,7 +6,8 @@ package org.bukkit.entity; public interface Boat extends Vehicle { /** - * Gets the maximum speed of a boat. The speed is unrelated to the velocity. + * Gets the maximum speed of a boat. The speed is unrelated to the + * velocity. * * @return The max speed. */ diff --git a/src/main/java/org/bukkit/entity/ComplexLivingEntity.java b/src/main/java/org/bukkit/entity/ComplexLivingEntity.java index 2670d17b..f74411c3 100644 --- a/src/main/java/org/bukkit/entity/ComplexLivingEntity.java +++ b/src/main/java/org/bukkit/entity/ComplexLivingEntity.java @@ -3,7 +3,8 @@ package org.bukkit.entity; import java.util.Set; /** - * Represents a complex living entity - one that is made up of various smaller parts + * Represents a complex living entity - one that is made up of various smaller + * parts */ public interface ComplexLivingEntity extends LivingEntity { /** diff --git a/src/main/java/org/bukkit/entity/Creature.java b/src/main/java/org/bukkit/entity/Creature.java index 3a3912da..f223f55b 100644 --- a/src/main/java/org/bukkit/entity/Creature.java +++ b/src/main/java/org/bukkit/entity/Creature.java @@ -1,13 +1,15 @@ package org.bukkit.entity; /** - * Represents a Creature. Creatures are non-intelligent monsters or animals which - * have very simple abilities. + * Represents a Creature. Creatures are non-intelligent monsters or animals + * which have very simple abilities. */ public interface Creature extends LivingEntity { /** - * Instructs this Creature to set the specified LivingEntity as its target. + * Instructs this Creature to set the specified LivingEntity as its + * target. + * <p> * Hostile creatures may attack their target, and friendly creatures may * follow their target. * diff --git a/src/main/java/org/bukkit/entity/Damageable.java b/src/main/java/org/bukkit/entity/Damageable.java index 3097b9ad..53877a84 100644 --- a/src/main/java/org/bukkit/entity/Damageable.java +++ b/src/main/java/org/bukkit/entity/Damageable.java @@ -20,7 +20,8 @@ public interface Damageable extends Entity { void _INVALID_damage(int amount); /** - * Deals the given amount of damage to this entity, from a specified entity. + * Deals the given amount of damage to this entity, from a specified + * entity. * * @param amount Amount of damage to deal * @param source Entity which to attribute this damage from @@ -51,10 +52,12 @@ public interface Damageable extends Entity { int _INVALID_getHealth(); /** - * Sets the entity's health from 0 to {@link #getMaxHealth()}, where 0 is dead. + * Sets the entity's health from 0 to {@link #getMaxHealth()}, where 0 is + * dead. * * @param health New health represented from 0 to max - * @throws IllegalArgumentException Thrown if the health is < 0 or > {@link #getMaxHealth()} + * @throws IllegalArgumentException Thrown if the health is < 0 or > + * {@link #getMaxHealth()} */ void setHealth(double health); @@ -84,9 +87,11 @@ public interface Damageable extends Entity { /** * Sets the maximum health this entity can have. * <p> - * If the health of the entity is above the value provided it will be set to that value. + * If the health of the entity is above the value provided it will be set + * to that value. * <p> - * Note: An entity with a health bar ({@link Player}, {@link EnderDragon}, {@link Wither}, etc...} will have their bar scaled accordingly. + * Note: An entity with a health bar ({@link Player}, {@link EnderDragon}, + * {@link Wither}, etc...} will have their bar scaled accordingly. * * @param health amount of health to set the maximum to */ diff --git a/src/main/java/org/bukkit/entity/EnderSignal.java b/src/main/java/org/bukkit/entity/EnderSignal.java index 49a21ad3..3d2d76cf 100644 --- a/src/main/java/org/bukkit/entity/EnderSignal.java +++ b/src/main/java/org/bukkit/entity/EnderSignal.java @@ -1,7 +1,8 @@ package org.bukkit.entity; /** - * Represents an Ender Signal, which is often created upon throwing an ender eye + * Represents an Ender Signal, which is often created upon throwing an ender + * eye */ public interface EnderSignal extends Entity { diff --git a/src/main/java/org/bukkit/entity/Entity.java b/src/main/java/org/bukkit/entity/Entity.java index 72af4fa1..396ea208 100644 --- a/src/main/java/org/bukkit/entity/Entity.java +++ b/src/main/java/org/bukkit/entity/Entity.java @@ -25,8 +25,10 @@ public interface Entity extends Metadatable { public Location getLocation(); /** - * Stores the entity's current position in the provided Location object.<br /> - * If the provided Location is null this method does nothing and returns null. + * Stores the entity's current position in the provided Location object. + * <p> + * If the provided Location is null this method does nothing and returns + * null. * * @return The Location object provided or null */ @@ -47,8 +49,9 @@ public interface Entity extends Metadatable { public Vector getVelocity(); /** - * Returns true if the entity is supported by a block. This value is a state - * updated by the server and is not recalculated unless the entity moves. + * Returns true if the entity is supported by a block. This value is a + * state updated by the server and is not recalculated unless the entity + * moves. * * @return True if entity is on ground. */ @@ -96,7 +99,8 @@ public interface Entity extends Metadatable { public boolean teleport(Entity destination, TeleportCause cause); /** - * Returns a list of entities within a bounding box centered around this entity + * Returns a list of entities within a bounding box centered around this + * entity * * @param x 1/2 the size of the box along x axis * @param y 1/2 the size of the box along y axis @@ -113,7 +117,8 @@ public interface Entity extends Metadatable { public int getEntityId(); /** - * Returns the entity's current fire ticks (ticks before the entity stops being on fire). + * Returns the entity's current fire ticks (ticks before the entity stops + * being on fire). * * @return int fireTicks */ @@ -127,7 +132,8 @@ public interface Entity extends Metadatable { public int getMaxFireTicks(); /** - * Sets the entity's current fire ticks (ticks before the entity stops being on fire). + * Sets the entity's current fire ticks (ticks before the entity stops + * being on fire). * * @param ticks Current ticks remaining */ @@ -148,6 +154,7 @@ public interface Entity extends Metadatable { /** * Returns false if the entity has died or been despawned for some other * reason. + * * @return True if valid. */ public boolean isValid(); @@ -211,9 +218,11 @@ public interface Entity extends Metadatable { public void setLastDamageCause(EntityDamageEvent event); /** - * Retrieve the last {@link EntityDamageEvent} inflicted on this entity. This event may have been cancelled. + * Retrieve the last {@link EntityDamageEvent} inflicted on this entity. + * This event may have been cancelled. * - * @return the last known {@link EntityDamageEvent} or null if hitherto unharmed + * @return the last known {@link EntityDamageEvent} or null if hitherto + * unharmed */ public EntityDamageEvent getLastDamageCause(); @@ -236,7 +245,8 @@ public interface Entity extends Metadatable { /** * Sets the amount of ticks this entity has lived for. * <p> - * This is the equivalent to "age" in entities. May not be less than one tick. + * This is the equivalent to "age" in entities. May not be less than one + * tick. * * @param value Age of entity */ @@ -253,6 +263,7 @@ public interface Entity extends Metadatable { /** * Get the type of the entity. + * * @return The entity type. */ public EntityType getType(); @@ -265,9 +276,9 @@ public interface Entity extends Metadatable { public boolean isInsideVehicle(); /** - * Leave the current vehicle. If the entity is currently in a vehicle - * (and is removed from it), true will be returned, otherwise false will - * be returned. + * Leave the current vehicle. If the entity is currently in a vehicle (and + * is removed from it), true will be returned, otherwise false will be + * returned. * * @return True if the entity was in a vehicle. */ diff --git a/src/main/java/org/bukkit/entity/EntityType.java b/src/main/java/org/bukkit/entity/EntityType.java index 74837999..39ecb130 100644 --- a/src/main/java/org/bukkit/entity/EntityType.java +++ b/src/main/java/org/bukkit/entity/EntityType.java @@ -20,8 +20,8 @@ public enum EntityType { /** * An item resting on the ground. * <p> - * Spawn with {@link World#dropItem(Location, ItemStack)} - * or {@link World#dropItemNaturally(Location, ItemStack)} + * Spawn with {@link World#dropItem(Location, ItemStack)} or {@link + * World#dropItemNaturally(Location, ItemStack)} */ DROPPED_ITEM("Item", Item.class, 1, false), /** @@ -158,7 +158,7 @@ public enum EntityType { FISHING_HOOK(null, Fish.class, -1, false), /** * A bolt of lightning. - * + * <p> * Spawn with {@link World#strikeLightning(Location)}. */ LIGHTNING(null, LightningStrike.class, -1, false), @@ -250,9 +250,10 @@ public enum EntityType { } /** - * Some entities cannot be spawned using {@link World#spawnEntity(Location, EntityType)} - * or {@link World#spawn(Location, Class)}, usually - * because they require additional information in order to spawn. + * Some entities cannot be spawned using {@link + * World#spawnEntity(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/Fireball.java b/src/main/java/org/bukkit/entity/Fireball.java index 88876a47..56ed5789 100644 --- a/src/main/java/org/bukkit/entity/Fireball.java +++ b/src/main/java/org/bukkit/entity/Fireball.java @@ -10,8 +10,7 @@ public interface Fireball extends Projectile, Explosive { /** * Fireballs fly straight and do not take setVelocity(...) well. * - * @param direction - * the direction this fireball is flying toward + * @param direction the direction this fireball is flying toward */ public void setDirection(Vector direction); diff --git a/src/main/java/org/bukkit/entity/Fish.java b/src/main/java/org/bukkit/entity/Fish.java index 25e58b08..9ecc4a33 100644 --- a/src/main/java/org/bukkit/entity/Fish.java +++ b/src/main/java/org/bukkit/entity/Fish.java @@ -22,7 +22,8 @@ public interface Fish extends Projectile { * 1.0 = Instant catch. * * @param chance the bite chance - * @throws IllegalArgumentException if the bite chance is not between 0 and 1 + * @throws IllegalArgumentException if the bite chance is not between 0 + * and 1 */ public void setBiteChance(double chance) throws IllegalArgumentException; } diff --git a/src/main/java/org/bukkit/entity/Hanging.java b/src/main/java/org/bukkit/entity/Hanging.java index 0b1979d9..67e9b615 100644 --- a/src/main/java/org/bukkit/entity/Hanging.java +++ b/src/main/java/org/bukkit/entity/Hanging.java @@ -9,12 +9,14 @@ import org.bukkit.material.Attachable; public interface Hanging extends Entity, Attachable { /** - * Sets the direction of the hanging entity, potentially overriding rules of placement. Note that if the result - * is not valid the object would normally drop as an item. + * Sets the direction of the hanging entity, potentially overriding rules + * of placement. Note that if the result is not valid the object would + * normally drop as an item. * * @param face The new direction. * @param force Whether to force it. - * @return False if force was false and there was no block for it to attach to in order to face the given direction. + * @return False if force was false and there was no block for it to + * attach to in order to face the given direction. */ public boolean setFacingDirection(BlockFace face, boolean force); } diff --git a/src/main/java/org/bukkit/entity/HumanEntity.java b/src/main/java/org/bukkit/entity/HumanEntity.java index 4464ea60..6f70db4d 100644 --- a/src/main/java/org/bukkit/entity/HumanEntity.java +++ b/src/main/java/org/bukkit/entity/HumanEntity.java @@ -24,7 +24,8 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv /** * Get the player's inventory. * - * @return The inventory of the player, this also contains the armor slots. + * @return The inventory of the player, this also contains the armor + * slots. */ public PlayerInventory getInventory(); @@ -36,8 +37,8 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv public Inventory getEnderChest(); /** - * If the player currently has an inventory window open, this method will set a - * property of that window, such as the state of a progress bar. + * If the player currently has an inventory window open, this method will + * set a property of that window, such as the state of a progress bar. * * @param prop The property. * @param value The value to set the property to. @@ -46,16 +47,16 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv public boolean setWindowProperty(InventoryView.Property prop, int value); /** - * Gets the inventory view the player is currently viewing. If they do not have - * an inventory window open, it returns their internal crafting view. + * Gets the inventory view the player is currently viewing. If they do not + * have an inventory window open, it returns their internal crafting view. * * @return The inventory view. */ public InventoryView getOpenInventory(); /** - * Opens an inventory window with the specified inventory on the top and the player's inventory - * on the bottom. + * Opens an inventory window with the specified inventory on the top and + * the player's inventory on the bottom. * * @param inventory The inventory to open * @return The newly opened inventory view @@ -63,22 +64,28 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv public InventoryView openInventory(Inventory inventory); /** - * Opens an empty workbench inventory window with the player's inventory on the bottom. + * Opens an empty workbench inventory window with the player's inventory + * on the bottom. * - * @param location The location to attach it to. If null, the player's location is used. - * @param force If false, and there is no workbench block at the location, no inventory will be - * opened and null will be returned. - * @return The newly opened inventory view, or null if it could not be opened. + * @param location The location to attach it to. If null, the player's + * location is used. + * @param force If false, and there is no workbench block at the location, + * no inventory will be opened and null will be returned. + * @return The newly opened inventory view, or null if it could not be + * opened. */ public InventoryView openWorkbench(Location location, boolean force); /** - * Opens an empty enchanting inventory window with the player's inventory on the bottom. + * Opens an empty enchanting inventory window with the player's inventory + * on the bottom. * - * @param location The location to attach it to. If null, the player's location is used. - * @param force If false, and there is no enchanting table at the location, no inventory will be - * opened and null will be returned. - * @return The newly opened inventory view, or null if it could not be opened. + * @param location The location to attach it to. If null, the player's + * location is used. + * @param force If false, and there is no enchanting table at the + * location, no inventory will be opened and null will be returned. + * @return The newly opened inventory view, or null if it could not be + * opened. */ public InventoryView openEnchanting(Location location, boolean force); @@ -110,8 +117,8 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv public void setItemInHand(ItemStack item); /** - * Returns the ItemStack currently on your cursor, can be empty. - * Will always be empty if the player currently has no open window. + * Returns the ItemStack currently on your cursor, can be empty. Will + * always be empty if the player currently has no open window. * * @return The ItemStack of the item you are currently moving around. */ @@ -119,7 +126,8 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv /** * Sets the item to the given ItemStack, this will replace whatever the - * user was moving. Will always be empty if the player currently has no open window. + * user was moving. Will always be empty if the player currently has no + * open window. * * @param item The ItemStack which will end up in the hand */ diff --git a/src/main/java/org/bukkit/entity/IronGolem.java b/src/main/java/org/bukkit/entity/IronGolem.java index 04290eb6..655e37cb 100644 --- a/src/main/java/org/bukkit/entity/IronGolem.java +++ b/src/main/java/org/bukkit/entity/IronGolem.java @@ -15,9 +15,8 @@ public interface IronGolem extends Golem { /** * Sets whether this iron golem was built by a player or not. * - * @param playerCreated - * true if you want to set the iron golem as being player created, - * false if you want it to be a natural village golem. + * @param playerCreated true if you want to set the iron golem as being + * player created, false if you want it to be a natural village golem. */ public void setPlayerCreated(boolean playerCreated); } diff --git a/src/main/java/org/bukkit/entity/LivingEntity.java b/src/main/java/org/bukkit/entity/LivingEntity.java index 4519dc4d..89926b29 100644 --- a/src/main/java/org/bukkit/entity/LivingEntity.java +++ b/src/main/java/org/bukkit/entity/LivingEntity.java @@ -25,15 +25,14 @@ public interface LivingEntity extends Entity, Damageable { /** * Gets the height of the living entity's eyes above its Location. * - * @param ignoreSneaking if set to true, the effects of sneaking - * will be ignored + * @param ignoreSneaking if set to true, the effects of sneaking will be + * ignored * @return height of the living entity's eyes above its location */ public double getEyeHeight(boolean ignoreSneaking); /** - * Get a Location detailing the current eye position of the living - * entity. + * Get a Location detailing the current eye position of the living entity. * * @return a location at the eyes of the living entity */ @@ -42,15 +41,15 @@ public interface LivingEntity extends Entity, Damageable { /** * Gets all blocks along the living entity's line of sight. * <p> - * This list contains all blocks from the living entity's eye position - * to target inclusive. - * - * @param transparent HashSet containing all transparent block IDs - * (set to null for only air) - * @param maxDistance this is the maximum distance to scan (may be - * limited by server by at least 100 blocks, no less) - * @return list containing all blocks along the living entity's line - * of sight + * This list contains all blocks from the living entity's eye position to + * target inclusive. + * + * @param transparent HashSet containing all transparent block IDs (set to + * null for only air) + * @param maxDistance this is the maximum distance to scan (may be limited + * by server by at least 100 blocks, no less) + * @return list containing all blocks along the living entity's line of + * sight * @deprecated Magic value */ @Deprecated @@ -59,10 +58,10 @@ public interface LivingEntity extends Entity, Damageable { /** * Gets the block that the living entity has targeted. * - * @param transparent HashSet containing all transparent block IDs - * (set to null for only air) - * @param maxDistance this is the maximum distance to scan - * (may be limited by server by at least 100 blocks, no less) + * @param transparent HashSet containing all transparent block IDs (set to + * null for only air) + * @param maxDistance this is the maximum distance to scan (may be limited + * by server by at least 100 blocks, no less) * @return block that the living entity has targeted * @deprecated Magic value */ @@ -74,8 +73,8 @@ public interface LivingEntity extends Entity, Damageable { * <p> * The target block will be the last block in the list. * - * @param transparent HashSet containing all transparent block IDs - * (set to null for only air) + * @param transparent HashSet containing all transparent block IDs (set to + * null for only air) * @param maxDistance this is the maximum distance to scan. This may be * further limited by the server, but never to less than 100 blocks * @return list containing the last 2 blocks along the living entity's @@ -129,16 +128,14 @@ public interface LivingEntity extends Entity, Damageable { public int getRemainingAir(); /** - * Sets the amount of air that the living entity has remaining, in - * ticks. + * Sets the amount of air that the living entity has remaining, in ticks. * * @param ticks amount of air remaining */ public void setRemainingAir(int ticks); /** - * Returns the maximum amount of air the living entity can - * have, in ticks. + * Returns the maximum amount of air the living entity can have, in ticks. * * @return maximum amount of air */ @@ -154,8 +151,8 @@ public interface LivingEntity extends Entity, Damageable { /** * Returns the living entity's current maximum no damage ticks. * <p> - * This is the maximum duration in which the living entity will not - * take damage. + * This is the maximum duration in which the living entity will not take + * damage. * * @return maximum no damage ticks */ @@ -169,8 +166,8 @@ public interface LivingEntity extends Entity, Damageable { public void setMaximumNoDamageTicks(int ticks); /** - * Returns the living entity's last damage taken in the current no - * damage ticks time. + * Returns the living entity's last damage taken in the current no damage + * ticks time. * <p> * Only damage higher than this amount will further damage the living * entity. @@ -228,8 +225,8 @@ public interface LivingEntity extends Entity, Damageable { /** * Adds the given {@link PotionEffect} to the living entity. * <p> - * Only one potion effect can be present for a given - * {@link PotionEffectType}. + * Only one potion effect can be present for a given {@link + * PotionEffectType}. * * @param effect PotionEffect to be added * @return whether the effect could be added @@ -239,8 +236,8 @@ public interface LivingEntity extends Entity, Damageable { /** * Adds the given {@link PotionEffect} to the living entity. * <p> - * Only one potion effect can be present for a given - * {@link PotionEffectType}. + * Only one potion effect can be present for a given {@link + * PotionEffectType}. * * @param effect PotionEffect to be added * @param force whether conflicting effects should be removed @@ -262,8 +259,7 @@ public interface LivingEntity extends Entity, Damageable { * the given {@link PotionEffectType} applied to it. * * @param type the potion type to check - * @return whether the living entity has this potion effect active - * on them + * @return whether the living entity has this potion effect active on them */ public boolean hasPotionEffect(PotionEffectType type); @@ -275,8 +271,8 @@ public interface LivingEntity extends Entity, Damageable { public void removePotionEffect(PotionEffectType type); /** - * Returns all currently active {@link PotionEffect}s on the - * living entity. + * Returns all currently active {@link PotionEffect}s on the living + * entity. * * @return a collection of {@link PotionEffect}s */ @@ -285,8 +281,8 @@ public interface LivingEntity extends Entity, Damageable { /** * Checks whether the living entity has block line of sight to another. * <p> - * This uses the same algorithm that hostile mobs use to find the - * closest player. + * This uses the same algorithm that hostile mobs use to find the closest + * player. * * @param other the entity to determine line of sight to * @return true if there is a line of sight, false if not @@ -303,8 +299,8 @@ public interface LivingEntity extends Entity, Damageable { public boolean getRemoveWhenFarAway(); /** - * Sets whether or not the living entity despawns when away from - * players or not. + * Sets whether or not the living entity despawns when away from players + * or not. * * @param remove the removal status */ @@ -332,8 +328,8 @@ public interface LivingEntity extends Entity, Damageable { public boolean getCanPickupItems(); /** - * Sets a custom name on a mob. This name will be used in death - * messages and can be sent to the client as a nameplate over the mob. + * Sets a custom name on a mob. This name will be used in death messages + * and can be sent to the client as a nameplate over the mob. * <p> * Setting the name to null or an empty string will clear it. * <p> @@ -356,8 +352,8 @@ public interface LivingEntity extends Entity, Damageable { public String getCustomName(); /** - * Sets whether or not to display the mob's custom name client side. - * The name will be displayed above the mob similarly to a player. + * Sets whether or not to display the mob's custom name client side. The + * name will be displayed above the mob similarly to a player. * <p> * This value has no effect on players, they will always display their * name. diff --git a/src/main/java/org/bukkit/entity/Minecart.java b/src/main/java/org/bukkit/entity/Minecart.java index 00ccd8e8..a7bb0944 100644 --- a/src/main/java/org/bukkit/entity/Minecart.java +++ b/src/main/java/org/bukkit/entity/Minecart.java @@ -8,9 +8,9 @@ import org.bukkit.util.Vector; public interface Minecart extends Vehicle { /** - * This method exists for legacy reasons to provide backwards compatibility. - * It will not exist at runtime and should not be used under any - * circumstances. + * This method exists for legacy reasons to provide backwards + * compatibility. It will not exist at runtime and should not be used + * under any circumstances. */ @Deprecated public void _INVALID_setDamage(int damage); @@ -23,9 +23,9 @@ public interface Minecart extends Vehicle { public void setDamage(double damage); /** - * This method exists for legacy reasons to provide backwards compatibility. - * It will not exist at runtime and should not be used under any - * circumstances. + * This method exists for legacy reasons to provide backwards + * compatibility. It will not exist at runtime and should not be used + * under any circumstances. */ @Deprecated public int _INVALID_getDamage(); @@ -38,51 +38,58 @@ public interface Minecart extends Vehicle { public double getDamage(); /** - * Gets the maximum speed of a minecart. The speed is unrelated to the velocity. + * Gets the maximum speed of a minecart. The speed is unrelated to the + * velocity. * * @return The max speed */ public double getMaxSpeed(); /** - * Sets the maximum speed of a minecart. Must be nonnegative. Default is 0.4D. + * Sets the maximum speed of a minecart. Must be nonnegative. Default is + * 0.4D. * * @param speed The max speed */ public void setMaxSpeed(double speed); /** - * Returns whether this minecart will slow down faster without a passenger occupying it + * Returns whether this minecart will slow down faster without a passenger + * occupying it * * @return Whether it decelerates faster */ public boolean isSlowWhenEmpty(); /** - * Sets whether this minecart will slow down faster without a passenger occupying it + * Sets whether this minecart will slow down faster without a passenger + * occupying it * * @param slow Whether it will decelerate faster */ public void setSlowWhenEmpty(boolean slow); /** - * Gets the flying velocity modifier. Used for minecarts that are in mid-air. - * A flying minecart's velocity is multiplied by this factor each tick. + * Gets the flying velocity modifier. Used for minecarts that are in + * mid-air. A flying minecart's velocity is multiplied by this factor each + * tick. * * @return The vector factor */ public Vector getFlyingVelocityMod(); /** - * Sets the flying velocity modifier. Used for minecarts that are in mid-air. - * A flying minecart's velocity is multiplied by this factor each tick. + * Sets the flying velocity modifier. Used for minecarts that are in + * mid-air. A flying minecart's velocity is multiplied by this factor each + * tick. * * @param flying velocity modifier vector */ public void setFlyingVelocityMod(Vector flying); /** - * Gets the derailed velocity modifier. Used for minecarts that are on the ground, but not on rails. + * Gets the derailed velocity modifier. Used for minecarts that are on the + * ground, but not on rails. * <p> * A derailed minecart's velocity is multiplied by this factor each tick. * @@ -91,8 +98,9 @@ public interface Minecart extends Vehicle { public Vector getDerailedVelocityMod(); /** - * Sets the derailed velocity modifier. Used for minecarts that are on the ground, but not on rails. - * A derailed minecart's velocity is multiplied by this factor each tick. + * Sets the derailed velocity modifier. Used for minecarts that are on the + * ground, but not on rails. A derailed minecart's velocity is multiplied + * by this factor each tick. * * @param derailed visible speed */ diff --git a/src/main/java/org/bukkit/entity/Ocelot.java b/src/main/java/org/bukkit/entity/Ocelot.java index 4016d3fa..d5d034d8 100644 --- a/src/main/java/org/bukkit/entity/Ocelot.java +++ b/src/main/java/org/bukkit/entity/Ocelot.java @@ -28,8 +28,8 @@ public interface Ocelot extends Animals, Tameable { public boolean isSitting(); /** - * Sets if this ocelot is sitting - * Will remove any path that the ocelot was following beforehand. + * Sets if this ocelot is sitting. Will remove any path that the ocelot + * was following beforehand. * * @param sitting true if sitting */ diff --git a/src/main/java/org/bukkit/entity/Painting.java b/src/main/java/org/bukkit/entity/Painting.java index ddfa89d3..ca7a4cfa 100644 --- a/src/main/java/org/bukkit/entity/Painting.java +++ b/src/main/java/org/bukkit/entity/Painting.java @@ -19,7 +19,8 @@ public interface Painting extends Hanging { * Set the art on this painting * * @param art The new art - * @return False if the new art won't fit at the painting's current location + * @return False if the new art won't fit at the painting's current + * location */ public boolean setArt(Art art); @@ -27,10 +28,12 @@ public interface Painting extends Hanging { * Set the art on this painting * * @param art The new art - * @param force If true, force the new art regardless of whether it fits at the current location - * Note that forcing it where it can't fit normally causes it to drop as an item unless you override - * this by catching the {@link PaintingBreakEvent}. - * @return False if force was false and the new art won't fit at the painting's current location + * @param force If true, force the new art regardless of whether it fits + * at the current location. Note that forcing it where it can't fit + * normally causes it to drop as an item unless you override this by + * catching the {@link PaintingBreakEvent}. + * @return False if force was false and the new art won't fit at the + * painting's current location */ public boolean setArt(Art art, boolean force); } diff --git a/src/main/java/org/bukkit/entity/PigZombie.java b/src/main/java/org/bukkit/entity/PigZombie.java index 65a3f8cd..2f086728 100644 --- a/src/main/java/org/bukkit/entity/PigZombie.java +++ b/src/main/java/org/bukkit/entity/PigZombie.java @@ -15,7 +15,8 @@ public interface PigZombie extends Zombie { /** * Set the pig zombie's current anger level. * - * @param level The anger level. Higher levels of anger take longer to wear off. + * @param level The anger level. Higher levels of anger take longer to + * wear off. */ void setAnger(int level); diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java index 3ec374b4..1a71fcd7 100644 --- a/src/main/java/org/bukkit/entity/Player.java +++ b/src/main/java/org/bukkit/entity/Player.java @@ -25,20 +25,22 @@ import org.bukkit.scoreboard.Scoreboard; public interface Player extends HumanEntity, Conversable, CommandSender, OfflinePlayer, PluginMessageRecipient { /** - * Gets the "friendly" name to display of this player. This may include color. + * Gets the "friendly" name to display of this player. This may include + * color. * <p> - * Note that this name will not be displayed in game, only in chat and places - * defined by plugins + * Note that this name will not be displayed in game, only in chat and + * places defined by plugins. * * @return the friendly name */ public String getDisplayName(); /** - * Sets the "friendly" name to display of this player. This may include color. + * Sets the "friendly" name to display of this player. This may include + * color. * <p> - * Note that this name will not be displayed in game, only in chat and places - * defined by plugins + * Note that this name will not be displayed in game, only in chat and + * places defined by plugins. * * @param name The new display name. */ @@ -54,20 +56,22 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline /** * Sets the name that is shown on the in-game player list. * <p> - * The name cannot be longer than 16 characters, but {@link ChatColor} is supported. + * The name cannot be longer than 16 characters, but {@link ChatColor} is + * supported. * <p> * If the value is null, the name will be identical to {@link #getName()}. * <p> - * This name is case sensitive and unique, two names with different casing will - * appear as two different people. If a player joins afterwards with - * a name that conflicts with a player's custom list name, the - * joining player's player list name will have a random number appended to it - * (1-2 characters long in the default implementation). If the joining - * player's name is 15 or 16 characters long, part of the name will - * be truncated at the end to allow the addition of the two digits. + * This name is case sensitive and unique, two names with different casing + * will appear as two different people. If a player joins afterwards with + * a name that conflicts with a player's custom list name, the joining + * player's player list name will have a random number appended to it (1-2 + * characters long in the default implementation). If the joining player's + * name is 15 or 16 characters long, part of the name will be truncated at + * the end to allow the addition of the two digits. * * @param name new player list name - * @throws IllegalArgumentException if the name is already used by someone else + * @throws IllegalArgumentException if the name is already used by someone + * else * @throws IllegalArgumentException if the length of the name is too long */ public void setPlayerListName(String name); @@ -151,14 +155,19 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline public void setSprinting(boolean sprinting); /** - * Saves the players current location, health, inventory, motion, and other information into the username.dat file, in the world/player folder + * Saves the players current location, health, inventory, motion, and + * other information into the username.dat file, in the world/player + * folder */ public void saveData(); /** - * Loads the players current location, health, inventory, motion, and other information from the username.dat file, in the world/player folder + * Loads the players current location, health, inventory, motion, and + * other information from the username.dat file, in the world/player + * folder. * <p> - * Note: This will overwrite the players current inventory, health, motion, etc, with the state from the saved dat file. + * Note: This will overwrite the players current inventory, health, + * motion, etc, with the state from the saved dat file. */ public void loadData(); @@ -253,8 +262,8 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline public <T> void playEffect(Location loc, Effect effect, T data); /** - * Send a block change. This fakes a block change packet for a user at - * a certain location. This will not actually change the world in any way. + * Send a block change. This fakes a block change packet for a user at a + * certain location. This will not actually change the world in any way. * * @param loc The location of the changed block * @param material The new block @@ -265,13 +274,13 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline public void sendBlockChange(Location loc, Material material, byte data); /** - * Send a chunk change. This fakes a chunk change packet for a user at - * a certain location. The updated cuboid must be entirely within a single + * Send a chunk change. This fakes a chunk change packet for a user at a + * certain location. The updated cuboid must be entirely within a single * chunk. This will not actually change the world in any way. * <p> - * At least one of the dimensions of the cuboid must be even. The size of the - * data buffer must be 2.5*sx*sy*sz and formatted in accordance with the Packet51 - * format. + * At least one of the dimensions of the cuboid must be even. The size of + * the data buffer must be 2.5*sx*sy*sz and formatted in accordance with + * the Packet51 format. * * @param loc The location of the cuboid * @param sx The x size of the cuboid @@ -285,8 +294,8 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline public boolean sendChunkChange(Location loc, int sx, int sy, int sz, byte[] data); /** - * Send a block change. This fakes a block change packet for a user at - * a certain location. This will not actually change the world in any way. + * Send a block change. This fakes a block change packet for a user at a + * certain location. This will not actually change the world in any way. * * @param loc The location of the changed block * @param material The new block ID @@ -297,8 +306,8 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline public void sendBlockChange(Location loc, int material, byte data); /** - * Render a map and send it to the player in its entirety. This may be used - * when streaming the map in the normal manner is not desirable. + * Render a map and send it to the player in its entirety. This may be + * used when streaming the map in the normal manner is not desirable. * * @param map The map to be sent */ @@ -307,7 +316,8 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline /** * Forces an update of the player's entire inventory. * - * @deprecated This method should not be relied upon as it is a temporary work-around for a larger, more complicated issue. + * @deprecated This method should not be relied upon as it is a temporary + * work-around for a larger, more complicated issue. */ @Deprecated public void updateInventory(); @@ -352,14 +362,19 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline public void incrementStatistic(Statistic statistic, Material material, int amount); /** - * Sets the current time on the player's client. When relative is true the player's time - * will be kept synchronized to its world time with the specified offset. + * Sets the current time on the player's client. When relative is true the + * player's time will be kept synchronized to its world time with the + * specified offset. * <p> - * When using non relative time the player's time will stay fixed at the specified time parameter. It's up to - * the caller to continue updating the player's time. To restore player time to normal use resetPlayerTime(). + * When using non relative time the player's time will stay fixed at the + * specified time parameter. It's up to the caller to continue updating + * the player's time. To restore player time to normal use + * resetPlayerTime(). * - * @param time The current player's perceived time or the player's time offset from the server time. - * @param relative When true the player time is kept relative to its world time. + * @param time The current player's perceived time or the player's time + * offset from the server time. + * @param relative When true the player time is kept relative to its world + * time. */ public void setPlayerTime(long time, boolean relative); @@ -371,23 +386,26 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline public long getPlayerTime(); /** - * Returns the player's current time offset relative to server time, or the current player's fixed time - * if the player's time is absolute. + * Returns the player's current time offset relative to server time, or + * the current player's fixed time if the player's time is absolute. * * @return The player's time */ public long getPlayerTimeOffset(); /** - * Returns true if the player's time is relative to the server time, otherwise the player's time is absolute and - * will not change its current time unless done so with setPlayerTime(). + * Returns true if the player's time is relative to the server time, + * otherwise the player's time is absolute and will not change its current + * time unless done so with setPlayerTime(). * * @return true if the player's time is relative to the server time. */ public boolean isPlayerTimeRelative(); /** - * Restores the normal condition where the player's time is synchronized with the server time. + * Restores the normal condition where the player's time is synchronized + * with the server time. + * <p> * Equivalent to calling setPlayerTime(0, true). */ public void resetPlayerTime(); @@ -405,7 +423,7 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline * Returns the type of weather the player is currently experiencing. * * @return The WeatherType that the player is currently experiencing or - * null if player is seeing server weather. + * null if player is seeing server weather. */ public WeatherType getPlayerWeather(); @@ -423,7 +441,8 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline public void giveExp(int amount); /** - * Gives the player the amount of experience levels specified. Levels can be taken by specifying a negative amount. + * Gives the player the amount of experience levels specified. Levels can + * be taken by specifying a negative amount. * * @param amount amount of experience levels to give or take */ @@ -478,9 +497,9 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline /** * Gets the players current exhaustion level. * <p> - * Exhaustion controls how fast the food level drops. While you have a certain - * amount of exhaustion, your saturation will drop to zero, and then your food - * will drop to zero. + * Exhaustion controls how fast the food level drops. While you have a + * certain amount of exhaustion, your saturation will drop to zero, and + * then your food will drop to zero. * * @return Exhaustion level */ @@ -496,8 +515,8 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline /** * Gets the players current saturation level. * <p> - * Saturation is a buffer for food level. Your food level will not drop if you - * are saturated > 0. + * Saturation is a buffer for food level. Your food level will not drop if + * you are saturated > 0. * * @return Saturation level */ @@ -525,7 +544,8 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline public void setFoodLevel(int value); /** - * Gets the Location where the player will spawn at their bed, null if they have not slept in one or their current bed spawn is invalid. + * Gets the Location where the player will spawn at their bed, null if + * they have not slept in one or their current bed spawn is invalid. * * @return Bed Spawn Location if bed exists, otherwise null. */ @@ -542,19 +562,22 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline * Sets the Location where the player will spawn at their bed. * * @param location where to set the respawn location - * @param force whether to forcefully set the respawn location even if a valid bed is not present + * @param force whether to forcefully set the respawn location even if a + * valid bed is not present */ public void setBedSpawnLocation(Location location, boolean force); /** - * Determines if the Player is allowed to fly via jump key double-tap like in creative mode. + * Determines if the Player is allowed to fly via jump key double-tap like + * in creative mode. * * @return True if the player is allowed to fly. */ public boolean getAllowFlight(); /** - * Sets if the Player is allowed to fly via jump key double-tap like in creative mode. + * Sets if the Player is allowed to fly via jump key double-tap like in + * creative mode. * * @param flight If flight should be allowed. */ @@ -578,16 +601,19 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline * Checks to see if a player has been hidden from this player * * @param player Player to check - * @return True if the provided player is not being hidden from this player + * @return True if the provided player is not being hidden from this + * player */ public boolean canSee(Player player); /** - * Checks to see if this player is currently standing on a block. This information may - * not be reliable, as it is a state provided by the client, and may therefore not be accurate. + * Checks to see if this player is currently standing on a block. This + * information may not be reliable, as it is a state provided by the + * client, and may therefore not be accurate. * * @return True if the player standing on a solid block, else false. - * @deprecated Inconsistent with {@link org.bukkit.entity.Entity#isOnGround()} + * @deprecated Inconsistent with {@link + * org.bukkit.entity.Entity#isOnGround()} */ @Deprecated public boolean isOnGround(); @@ -607,18 +633,22 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline public void setFlying(boolean value); /** - * Sets the speed at which a client will fly. Negative values indicate reverse directions. + * Sets the speed at which a client will fly. Negative values indicate + * reverse directions. * * @param value The new speed, from -1 to 1. - * @throws IllegalArgumentException If new speed is less than -1 or greater than 1 + * @throws IllegalArgumentException If new speed is less than -1 or + * greater than 1 */ public void setFlySpeed(float value) throws IllegalArgumentException; /** - * Sets the speed at which a client will walk. Negative values indicate reverse directions. + * Sets the speed at which a client will walk. Negative values indicate + * reverse directions. * * @param value The new speed, from -1 to 1. - * @throws IllegalArgumentException If new speed is less than -1 or greater than 1 + * @throws IllegalArgumentException If new speed is less than -1 or + * greater than 1 */ public void setWalkSpeed(float value) throws IllegalArgumentException; @@ -639,21 +669,26 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline /** * Request that the player's client download and switch texture packs. * <p> - * The player's client will download the new texture pack asynchronously in the background, and - * will automatically switch to it once the download is complete. If the client has downloaded - * and cached the same texture pack in the past, it will perform a quick timestamp check over - * the network to determine if the texture pack has changed and needs to be downloaded again. - * When this request is sent for the very first time from a given server, the client will first - * display a confirmation GUI to the player before proceeding with the download. + * The player's client will download the new texture pack asynchronously + * in the background, and will automatically switch to it once the + * download is complete. If the client has downloaded and cached the same + * texture pack in the past, it will perform a quick timestamp check over + * the network to determine if the texture pack has changed and needs to + * be downloaded again. When this request is sent for the very first time + * from a given server, the client will first display a confirmation GUI + * to the player before proceeding with the download. * <p> * Notes: - * <ul> - * <li>Players can disable server textures on their client, in which case this method will have no affect on them.</li> - * <li>There is no concept of resetting texture packs back to default within Minecraft, so players will have to relog to do so.</li> - * </ul> - * - * @param url The URL from which the client will download the texture pack. The string must contain - * only US-ASCII characters and should be encoded as per RFC 1738. + * <ul> + * <li>Players can disable server textures on their client, in which + * case this method will have no affect on them. + * <li>There is no concept of resetting texture packs back to default + * within Minecraft, so players will have to relog to do so. + * </ul> + * + * @param url The URL from which the client will download the texture + * pack. The string must contain only US-ASCII characters and should + * be encoded as per RFC 1738. * @throws IllegalArgumentException Thrown if the URL is null. * @throws IllegalArgumentException Thrown if the URL is too long. */ diff --git a/src/main/java/org/bukkit/entity/Projectile.java b/src/main/java/org/bukkit/entity/Projectile.java index 148d2982..9d5e92d3 100644 --- a/src/main/java/org/bukkit/entity/Projectile.java +++ b/src/main/java/org/bukkit/entity/Projectile.java @@ -32,7 +32,8 @@ public interface Projectile extends Entity { public boolean doesBounce(); /** - * Set whether or not this projectile should bounce or not when it hits something. + * Set whether or not this projectile should bounce or not when it hits + * something. * * @param doesBounce whether or not it should bounce. */ diff --git a/src/main/java/org/bukkit/entity/TNTPrimed.java b/src/main/java/org/bukkit/entity/TNTPrimed.java index 295dcb9b..3ce322d9 100644 --- a/src/main/java/org/bukkit/entity/TNTPrimed.java +++ b/src/main/java/org/bukkit/entity/TNTPrimed.java @@ -22,16 +22,15 @@ public interface TNTPrimed extends Explosive { /** * Gets the source of this primed TNT. The source is the entity - * responsible for the creation of this primed TNT. - * (I.E. player ignites TNT with flint and steel.) Take note - * that this can be null if there is no suitable source. - * (created by the {@link org.bukkit.World#spawn(Location, Class)} - * method, for example.) + * responsible for the creation of this primed TNT. (I.E. player ignites + * TNT with flint and steel.) Take note that this can be null if there is + * no suitable source. (created by the {@link + * org.bukkit.World#spawn(Location, Class)} method, for example.) * <p> - * The source will become null if the chunk this primed TNT is in - * is unloaded then reloaded. If the source Entity becomes invalidated - * for any reason, such being removed from the world, the returned value - * will be null. + * The source will become null if the chunk this primed TNT is in is + * unloaded then reloaded. If the source Entity becomes invalidated for + * any reason, such being removed from the world, the returned value will + * be null. * * @return the source of this primed TNT */ diff --git a/src/main/java/org/bukkit/entity/Tameable.java b/src/main/java/org/bukkit/entity/Tameable.java index dea37639..014885da 100644 --- a/src/main/java/org/bukkit/entity/Tameable.java +++ b/src/main/java/org/bukkit/entity/Tameable.java @@ -5,16 +5,19 @@ public interface Tameable { /** * Check if this is tamed * <p> - * If something is tamed then a player can not tame it through normal methods, even if it does not belong to anyone in particular. + * If something is tamed then a player can not tame it through normal + * methods, even if it does not belong to anyone in particular. * * @return true if this has been tamed */ public boolean isTamed(); /** - * Sets if this has been tamed. Not necessary if the method setOwner has been used, as it tames automatically. + * Sets if this has been tamed. Not necessary if the method setOwner has + * been used, as it tames automatically. * <p> - * If something is tamed then a player can not tame it through normal methods, even if it does not belong to anyone in particular. + * If something is tamed then a player can not tame it through normal + * methods, even if it does not belong to anyone in particular. * * @param tame true if tame */ @@ -29,8 +32,10 @@ public interface Tameable { /** * Set this to be owned by given AnimalTamer. - * If the owner is not null, this will be tamed and will have any current path it is following removed. - * If the owner is set to null, this will be untamed, and the current owner removed. + * <p> + * If the owner is not null, this will be tamed and will have any current + * path it is following removed. If the owner is set to null, this will be + * untamed, and the current owner removed. * * @param tamer the AnimalTamer who should own this */ diff --git a/src/main/java/org/bukkit/entity/Wolf.java b/src/main/java/org/bukkit/entity/Wolf.java index 3cf0063b..9d5a896e 100644 --- a/src/main/java/org/bukkit/entity/Wolf.java +++ b/src/main/java/org/bukkit/entity/Wolf.java @@ -15,8 +15,10 @@ public interface Wolf extends Animals, Tameable { public boolean isAngry(); /** - * Sets the anger of this wolf - * An angry wolf can not be fed or tamed, and will actively look for targets to attack. + * Sets the anger of this wolf. + * <p> + * An angry wolf can not be fed or tamed, and will actively look for + * targets to attack. * * @param angry true if angry */ @@ -30,7 +32,8 @@ public interface Wolf extends Animals, Tameable { public boolean isSitting(); /** - * Sets if this wolf is sitting + * Sets if this wolf is sitting. + * <p> * Will remove any path that the wolf was following beforehand. * * @param sitting true if sitting diff --git a/src/main/java/org/bukkit/event/EventHandler.java b/src/main/java/org/bukkit/event/EventHandler.java index 1844e7a8..e42acc19 100644 --- a/src/main/java/org/bukkit/event/EventHandler.java +++ b/src/main/java/org/bukkit/event/EventHandler.java @@ -17,12 +17,12 @@ public @interface EventHandler { * <p> * First priority to the last priority executed: * <ol> - * <li>LOWEST</li> - * <li>LOW</li> - * <li>NORMAL</li> - * <li>HIGH</li> - * <li>HIGHEST</li> - * <li>MONITOR</li> + * <li>LOWEST + * <li>LOW + * <li>NORMAL + * <li>HIGH + * <li>HIGHEST + * <li>MONITOR * </ol> */ EventPriority priority() default EventPriority.NORMAL; diff --git a/src/main/java/org/bukkit/event/EventPriority.java b/src/main/java/org/bukkit/event/EventPriority.java index eb1400e0..ad381a79 100644 --- a/src/main/java/org/bukkit/event/EventPriority.java +++ b/src/main/java/org/bukkit/event/EventPriority.java @@ -29,7 +29,7 @@ public enum EventPriority { HIGHEST(4), /** * Event is listened to purely for monitoring the outcome of an event. - * <p/> + * <p> * No modifications to the event should be made under this priority */ MONITOR(5); diff --git a/src/main/java/org/bukkit/event/HandlerList.java b/src/main/java/org/bukkit/event/HandlerList.java index 4b97a71b..7d5efffb 100644 --- a/src/main/java/org/bukkit/event/HandlerList.java +++ b/src/main/java/org/bukkit/event/HandlerList.java @@ -12,14 +12,15 @@ import java.util.Map.Entry; public class HandlerList { /** - * Handler array. This field being an array is the key to this system's speed. + * Handler array. This field being an array is the key to this system's + * speed. */ private volatile RegisteredListener[] handlers = null; /** * Dynamic handler lists. These are changed using register() and - * unregister() and are automatically baked to the handlers array any - * time they have changed. + * unregister() and are automatically baked to the handlers array any time + * they have changed. */ private final EnumMap<EventPriority, ArrayList<RegisteredListener>> handlerslots; @@ -84,7 +85,8 @@ public class HandlerList { } /** - * Create a new handler list and initialize using EventPriority + * Create a new handler list and initialize using EventPriority. + * <p> * The HandlerList is then added to meta-list for use in bakeAll() */ public HandlerList() { @@ -191,7 +193,8 @@ public class HandlerList { } /** - * Get a specific plugin's registered listeners associated with this handler list + * Get a specific plugin's registered listeners associated with this + * handler list * * @param plugin the plugin to get the listeners of * @return the list of registered listeners diff --git a/src/main/java/org/bukkit/event/block/Action.java b/src/main/java/org/bukkit/event/block/Action.java index 0fc3af1a..25d26e3f 100644 --- a/src/main/java/org/bukkit/event/block/Action.java +++ b/src/main/java/org/bukkit/event/block/Action.java @@ -20,6 +20,14 @@ public enum Action { RIGHT_CLICK_AIR, /** * Stepping onto or into a block (Ass-pressure) + * + * Examples: + * <ul> + * <li>Jumping on soil + * <li>Standing on pressure plate + * <li>Triggering redstone ore + * <li>Triggering tripwire + * </ul> */ PHYSICAL, } diff --git a/src/main/java/org/bukkit/event/block/BlockBreakEvent.java b/src/main/java/org/bukkit/event/block/BlockBreakEvent.java index de9a2b49..a011f61a 100644 --- a/src/main/java/org/bukkit/event/block/BlockBreakEvent.java +++ b/src/main/java/org/bukkit/event/block/BlockBreakEvent.java @@ -8,20 +8,23 @@ import org.bukkit.event.HandlerList; /** * Called when a block is broken by a player. * <p> - * If you wish to have the block drop experience, you must set the experience value above 0. - * By default, experience will be set in the event if: + * If you wish to have the block drop experience, you must set the experience + * value above 0. By default, experience will be set in the event if: * <ol> - * <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 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 * </ol> * <p> * Note: - * Plugins wanting to simulate a traditional block drop should set the block to air and utilize their own methods for determining - * what the default drop for the block being broken is and what to do about it, if anything. + * Plugins wanting to simulate a traditional block drop should set the block + * to air and utilize their own methods for determining what the default drop + * for the block being broken is and what to do about it, if anything. * <p> - * If a Block Break event is cancelled, the block will not break and experience will not drop. + * If a Block Break event is cancelled, the block will not break and + * experience will not drop. */ public class BlockBreakEvent extends BlockExpEvent implements Cancellable { private final Player player; diff --git a/src/main/java/org/bukkit/event/block/BlockBurnEvent.java b/src/main/java/org/bukkit/event/block/BlockBurnEvent.java index 49bdccb6..1592a158 100644 --- a/src/main/java/org/bukkit/event/block/BlockBurnEvent.java +++ b/src/main/java/org/bukkit/event/block/BlockBurnEvent.java @@ -7,7 +7,8 @@ import org.bukkit.event.HandlerList; /** * Called when a block is destroyed as a result of being burnt by fire. * <p> - * If a Block Burn event is cancelled, the block will not be destroyed as a result of being burnt by fire. + * If a Block Burn event is cancelled, the block will not be destroyed as a + * result of being burnt by fire. */ public class BlockBurnEvent extends BlockEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); diff --git a/src/main/java/org/bukkit/event/block/BlockCanBuildEvent.java b/src/main/java/org/bukkit/event/block/BlockCanBuildEvent.java index 0db14821..3860f443 100644 --- a/src/main/java/org/bukkit/event/block/BlockCanBuildEvent.java +++ b/src/main/java/org/bukkit/event/block/BlockCanBuildEvent.java @@ -9,13 +9,16 @@ import org.bukkit.event.HandlerList; * <p> * Note: * <ul> - * <li>The Block returned by getBlock() is the block we are trying to place on, not the block we are trying to place.</li> - * <li>If you want to figure out what is being placed, use {@link #getMaterial()} or {@link #getMaterialId()} instead.</li> + * <li>The Block returned by getBlock() is the block we are trying to place + * on, not the block we are trying to place. + * <li>If you want to figure out what is being placed, use {@link + * #getMaterial()} or {@link #getMaterialId()} instead. * </ul> */ public class BlockCanBuildEvent extends BlockEvent { private static final HandlerList handlers = new HandlerList(); protected boolean buildable; + /** * * @deprecated Magic value @@ -36,7 +39,9 @@ public class BlockCanBuildEvent extends BlockEvent { /** * Gets whether or not the block can be built here. - * By default, returns Minecraft's answer on whether the block can be built here or not. + * <p> + * By default, returns Minecraft's answer on whether the block can be + * built here or not. * * @return boolean whether or not the block can be built */ @@ -47,7 +52,8 @@ public class BlockCanBuildEvent extends BlockEvent { /** * Sets whether the block can be built here or not. * - * @param cancel true if you want to allow the block to be built here despite Minecraft's default behaviour + * @param cancel true if you want to allow the block to be built here + * despite Minecraft's default behaviour */ public void setBuildable(boolean cancel) { this.buildable = cancel; diff --git a/src/main/java/org/bukkit/event/block/BlockDamageEvent.java b/src/main/java/org/bukkit/event/block/BlockDamageEvent.java index 01e9482d..d80e00ec 100644 --- a/src/main/java/org/bukkit/event/block/BlockDamageEvent.java +++ b/src/main/java/org/bukkit/event/block/BlockDamageEvent.java @@ -38,7 +38,8 @@ public class BlockDamageEvent extends BlockEvent implements Cancellable { /** * Gets if the block is set to instantly break when damaged by the player. * - * @return true if the block should instantly break when damaged by the player + * @return true if the block should instantly break when damaged by the + * player */ public boolean getInstaBreak() { return instaBreak; @@ -47,7 +48,8 @@ public class BlockDamageEvent extends BlockEvent implements Cancellable { /** * Sets if the block should instantly break when damaged by the player. * - * @param bool true if you want the block to instantly break when damaged by the player + * @param bool true if you want the block to instantly break when damaged + * by the player */ public void setInstaBreak(boolean bool) { this.instaBreak = bool; diff --git a/src/main/java/org/bukkit/event/block/BlockDispenseEvent.java b/src/main/java/org/bukkit/event/block/BlockDispenseEvent.java index 5d01beb0..16ee59b5 100644 --- a/src/main/java/org/bukkit/event/block/BlockDispenseEvent.java +++ b/src/main/java/org/bukkit/event/block/BlockDispenseEvent.java @@ -9,7 +9,8 @@ import org.bukkit.util.Vector; /** * Called when an item is dispensed from a block. * <p> - * If a Block Dispense event is cancelled, the block will not dispense the item. + * If a Block Dispense event is cancelled, the block will not dispense the + * item. */ public class BlockDispenseEvent extends BlockEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); @@ -24,8 +25,9 @@ public class BlockDispenseEvent extends BlockEvent implements Cancellable { } /** - * Gets the item that is being dispensed. Modifying the returned item - * will have no effect, you must use {@link #setItem(org.bukkit.inventory.ItemStack)} instead. + * Gets the item that is being dispensed. Modifying the returned item will + * have no effect, you must use {@link + * #setItem(org.bukkit.inventory.ItemStack)} instead. * * @return An ItemStack for the item being dispensed */ @@ -45,7 +47,8 @@ public class BlockDispenseEvent extends BlockEvent implements Cancellable { /** * Gets the velocity. * <p> - * Note: Modifying the returned Vector will not change the velocity, you must use {@link #setVelocity(org.bukkit.util.Vector)} instead. + * Note: Modifying the returned Vector will not change the velocity, you + * must use {@link #setVelocity(org.bukkit.util.Vector)} instead. * * @return A Vector for the dispensed item's velocity */ diff --git a/src/main/java/org/bukkit/event/block/BlockExpEvent.java b/src/main/java/org/bukkit/event/block/BlockExpEvent.java index 94ec5391..08636a29 100644 --- a/src/main/java/org/bukkit/event/block/BlockExpEvent.java +++ b/src/main/java/org/bukkit/event/block/BlockExpEvent.java @@ -26,7 +26,8 @@ public class BlockExpEvent extends BlockEvent { } /** - * Set the amount of experience dropped by the block after the event has processed + * Set the amount of experience dropped by the block after the event has + * processed * * @param exp 1 or higher to drop experience, else nothing will drop */ diff --git a/src/main/java/org/bukkit/event/block/BlockFadeEvent.java b/src/main/java/org/bukkit/event/block/BlockFadeEvent.java index 7d0120cb..673bc5f6 100644 --- a/src/main/java/org/bukkit/event/block/BlockFadeEvent.java +++ b/src/main/java/org/bukkit/event/block/BlockFadeEvent.java @@ -10,12 +10,13 @@ import org.bukkit.event.HandlerList; * <p> * Examples: * <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> + * <li>Snow melting due to being near a light source. + * <li>Ice melting due to being near a light source. + * <li>Fire burning out after time, without destroying fuel block. * </ul> * <p> - * If a Block Fade event is cancelled, the block will not fade, melt or disappear. + * If a Block Fade event is cancelled, the block will not fade, melt or + * disappear. */ public class BlockFadeEvent extends BlockEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); @@ -29,9 +30,11 @@ public class BlockFadeEvent extends BlockEvent implements Cancellable { } /** - * Gets the state of the block that will be fading, melting or disappearing. + * Gets the state of the block that will be fading, melting or + * disappearing. * - * @return The block state of the block that will be fading, melting or disappearing + * @return The block state of the block that will be fading, melting or + * disappearing */ public BlockState getNewState() { return newState; diff --git a/src/main/java/org/bukkit/event/block/BlockFormEvent.java b/src/main/java/org/bukkit/event/block/BlockFormEvent.java index 69a32efe..df0401f1 100644 --- a/src/main/java/org/bukkit/event/block/BlockFormEvent.java +++ b/src/main/java/org/bukkit/event/block/BlockFormEvent.java @@ -7,12 +7,14 @@ import org.bukkit.event.HandlerList; /** * Called when a block is formed or spreads based on world conditions. - * Use {@link BlockSpreadEvent} to catch blocks that actually spread and don't just "randomly" form. + * <p> + * Use {@link BlockSpreadEvent} to catch blocks that actually spread and don't + * just "randomly" form. * <p> * Examples: * <ul> - * <li>Snow forming due to a snow storm.</li> - * <li>Ice forming in a snowy Biome like Taiga or Tundra.</li> + * <li>Snow forming due to a snow storm. + * <li>Ice forming in a snowy Biome like Taiga or Tundra. * </ul> * <p> * If a Block Form event is cancelled, the block will not be formed. diff --git a/src/main/java/org/bukkit/event/block/BlockFromToEvent.java b/src/main/java/org/bukkit/event/block/BlockFromToEvent.java index 5ded4529..f976bea4 100644 --- a/src/main/java/org/bukkit/event/block/BlockFromToEvent.java +++ b/src/main/java/org/bukkit/event/block/BlockFromToEvent.java @@ -6,10 +6,11 @@ import org.bukkit.event.Cancellable; import org.bukkit.event.HandlerList; /** - * Represents events with a source block and a destination block, currently only applies to liquid (lava and water) - * and teleporting dragon eggs. + * Represents events with a source block and a destination block, currently + * only applies to liquid (lava and water) and teleporting dragon eggs. * <p> - * If a Block From To event is cancelled, the block will not move (the liquid will not flow). + * If a Block From To event is cancelled, the block will not move (the liquid + * will not flow). */ public class BlockFromToEvent extends BlockEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); diff --git a/src/main/java/org/bukkit/event/block/BlockGrowEvent.java b/src/main/java/org/bukkit/event/block/BlockGrowEvent.java index c4053778..2a959fd6 100644 --- a/src/main/java/org/bukkit/event/block/BlockGrowEvent.java +++ b/src/main/java/org/bukkit/event/block/BlockGrowEvent.java @@ -10,11 +10,11 @@ import org.bukkit.event.HandlerList; * <p> * Examples: * <ul> - * <li>Wheat</li> - * <li>Sugar Cane</li> - * <li>Cactus</li> - * <li>Watermelon</li> - * <li>Pumpkin</li> + * <li>Wheat + * <li>Sugar Cane + * <li>Cactus + * <li>Watermelon + * <li>Pumpkin * </ul> * <p> * If a Block Grow event is cancelled, the block will not grow. diff --git a/src/main/java/org/bukkit/event/block/BlockIgniteEvent.java b/src/main/java/org/bukkit/event/block/BlockIgniteEvent.java index e2b8c070..733a15ec 100644 --- a/src/main/java/org/bukkit/event/block/BlockIgniteEvent.java +++ b/src/main/java/org/bukkit/event/block/BlockIgniteEvent.java @@ -7,7 +7,8 @@ import org.bukkit.event.Cancellable; import org.bukkit.event.HandlerList; /** - * Called when a block is ignited. If you want to catch when a Player places fire, you need to use {@link BlockPlaceEvent}. + * Called when a block is ignited. If you want to catch when a Player places + * fire, you need to use {@link BlockPlaceEvent}. * <p> * If a Block Ignite event is cancelled, the block will not be ignited. */ @@ -19,7 +20,8 @@ public class BlockIgniteEvent extends BlockEvent implements Cancellable { private boolean cancel; /** - * Deprecated. Use {@link BlockIgniteEvent#BlockIgniteEvent(Block, IgniteCause, Entity)} instead. + * @deprecated use {@link BlockIgniteEvent#BlockIgniteEvent(Block, + * IgniteCause, Entity)} instead. */ @Deprecated public BlockIgniteEvent(final Block theBlock, final IgniteCause cause, final Player thePlayer) { diff --git a/src/main/java/org/bukkit/event/block/BlockPistonEvent.java b/src/main/java/org/bukkit/event/block/BlockPistonEvent.java index 2f489ba4..b89006f8 100644 --- a/src/main/java/org/bukkit/event/block/BlockPistonEvent.java +++ b/src/main/java/org/bukkit/event/block/BlockPistonEvent.java @@ -5,6 +5,9 @@ import org.bukkit.block.Block; import org.bukkit.block.BlockFace; import org.bukkit.event.Cancellable; +/** + * Called when a piston block is triggered + */ public abstract class BlockPistonEvent extends BlockEvent implements Cancellable { private boolean cancelled; private final BlockFace direction; diff --git a/src/main/java/org/bukkit/event/block/BlockPistonExtendEvent.java b/src/main/java/org/bukkit/event/block/BlockPistonExtendEvent.java index 18b40b3c..1058b8b8 100644 --- a/src/main/java/org/bukkit/event/block/BlockPistonExtendEvent.java +++ b/src/main/java/org/bukkit/event/block/BlockPistonExtendEvent.java @@ -8,6 +8,9 @@ import org.bukkit.block.Block; import org.bukkit.block.BlockFace; import org.bukkit.event.HandlerList; +/** + * Called when a piston extends + */ public class BlockPistonExtendEvent extends BlockPistonEvent { private static final HandlerList handlers = new HandlerList(); private final int length; @@ -29,7 +32,8 @@ public class BlockPistonExtendEvent extends BlockPistonEvent { } /** - * Get an immutable list of the blocks which will be moved by the extending. + * Get an immutable list of the blocks which will be moved by the + * extending. * * @return Immutable list of the moved blocks. */ diff --git a/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java b/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java index 9737b559..0190c4c4 100644 --- a/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java +++ b/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java @@ -5,6 +5,9 @@ import org.bukkit.block.Block; import org.bukkit.block.BlockFace; import org.bukkit.event.HandlerList; +/** + * Called when a piston retracts + */ public class BlockPistonRetractEvent extends BlockPistonEvent { private static final HandlerList handlers = new HandlerList(); public BlockPistonRetractEvent(final Block block, final BlockFace direction) { @@ -12,8 +15,8 @@ public class BlockPistonRetractEvent extends BlockPistonEvent { } /** - * Gets the location where the possible moving block might be if the retracting - * piston is sticky. + * Gets the location where the possible moving block might be if the + * retracting piston is sticky. * * @return The possible location of the possibly moving block. */ diff --git a/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java b/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java index a6ed55dd..6d0ffe81 100644 --- a/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java +++ b/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java @@ -49,8 +49,8 @@ public class BlockPlaceEvent extends BlockEvent implements Cancellable { } /** - * Clarity method for getting the placed block. Not really needed - * except for reasons of clarity. + * Clarity method for getting the placed block. Not really needed except + * for reasons of clarity. * * @return The Block that was placed */ @@ -59,7 +59,8 @@ public class BlockPlaceEvent extends BlockEvent implements Cancellable { } /** - * Gets the BlockState for the block which was replaced. Material type air mostly. + * Gets the BlockState for the block which was replaced. Material type air + * mostly. * * @return The BlockState for the block which was replaced. */ @@ -79,7 +80,8 @@ public class BlockPlaceEvent extends BlockEvent implements Cancellable { /** * Gets the item in the player's hand when they placed the block. * - * @return The ItemStack for the item in the player's hand when they placed the block + * @return The ItemStack for the item in the player's hand when they + * placed the block */ public ItemStack getItemInHand() { return itemInHand; diff --git a/src/main/java/org/bukkit/event/block/BlockSpreadEvent.java b/src/main/java/org/bukkit/event/block/BlockSpreadEvent.java index 5b54dafd..a1fb3634 100644 --- a/src/main/java/org/bukkit/event/block/BlockSpreadEvent.java +++ b/src/main/java/org/bukkit/event/block/BlockSpreadEvent.java @@ -6,12 +6,14 @@ import org.bukkit.event.HandlerList; /** * Called when a block spreads based on world conditions. - * Use {@link BlockFormEvent} to catch blocks that "randomly" form instead of actually spread. + * <p> + * Use {@link BlockFormEvent} to catch blocks that "randomly" form instead of + * actually spread. * <p> * Examples: * <ul> - * <li>Mushrooms spreading.</li> - * <li>Fire spreading.</li> + * <li>Mushrooms spreading. + * <li>Fire spreading. * </ul> * <p> * If a Block Spread event is cancelled, the block will not spread. diff --git a/src/main/java/org/bukkit/event/block/EntityBlockFormEvent.java b/src/main/java/org/bukkit/event/block/EntityBlockFormEvent.java index 98833e69..45efc321 100644 --- a/src/main/java/org/bukkit/event/block/EntityBlockFormEvent.java +++ b/src/main/java/org/bukkit/event/block/EntityBlockFormEvent.java @@ -9,7 +9,7 @@ import org.bukkit.entity.Entity; * <p> * Examples: * <ul> - * <li>Snow formed by a {@link org.bukkit.entity.Snowman}.</li> + * <li>Snow formed by a {@link org.bukkit.entity.Snowman}. * </ul> */ public class EntityBlockFormEvent extends BlockFormEvent { diff --git a/src/main/java/org/bukkit/event/block/NotePlayEvent.java b/src/main/java/org/bukkit/event/block/NotePlayEvent.java index 4a9778be..d4d43815 100644 --- a/src/main/java/org/bukkit/event/block/NotePlayEvent.java +++ b/src/main/java/org/bukkit/event/block/NotePlayEvent.java @@ -7,7 +7,8 @@ import org.bukkit.event.Cancellable; import org.bukkit.event.HandlerList; /** - * Called when a note block is being played through player interaction or a redstone current. + * Called when a note block is being played through player interaction or a + * redstone current. */ public class NotePlayEvent extends BlockEvent implements Cancellable { diff --git a/src/main/java/org/bukkit/event/enchantment/EnchantItemEvent.java b/src/main/java/org/bukkit/event/enchantment/EnchantItemEvent.java index 295ac52a..de28f1d9 100644 --- a/src/main/java/org/bukkit/event/enchantment/EnchantItemEvent.java +++ b/src/main/java/org/bukkit/event/enchantment/EnchantItemEvent.java @@ -13,7 +13,8 @@ import org.bukkit.inventory.InventoryView; import org.bukkit.inventory.ItemStack; /** - * Called when an ItemStack is successfully enchanted (currently at enchantment table) + * Called when an ItemStack is successfully enchanted (currently at + * enchantment table) */ public class EnchantItemEvent extends InventoryEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); @@ -82,8 +83,9 @@ public class EnchantItemEvent extends InventoryEvent implements Cancellable { } /** - * Get map of enchantment (levels, keyed by type) to be added to item (modify map returned to change values) - * Note: Any enchantments not allowed for the item will be ignored + * Get map of enchantment (levels, keyed by type) to be added to item + * (modify map returned to change values). Note: Any enchantments not + * allowed for the item will be ignored * * @return map of enchantment levels, keyed by enchantment */ diff --git a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java index 6028accb..6c0aa9ff 100644 --- a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java +++ b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java @@ -9,7 +9,8 @@ import org.bukkit.inventory.InventoryView; import org.bukkit.inventory.ItemStack; /** - * Called when an ItemStack is inserted in an enchantment table - can be called multiple times + * Called when an ItemStack is inserted in an enchantment table - can be + * called multiple times */ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); @@ -58,7 +59,8 @@ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellab } /** - * Get list of offered exp level costs of the enchantment (modify values to change offer) + * Get list of offered exp level costs of the enchantment (modify values + * to change offer) * * @return experience level costs offered */ diff --git a/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java b/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java index f60c86ff..3055ea77 100644 --- a/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java +++ b/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java @@ -53,7 +53,8 @@ public class CreatureSpawnEvent extends EntityEvent implements Cancellable { /** * Gets the type of creature being spawned. * - * @return A CreatureType value detailing the type of creature being spawned + * @return A CreatureType value detailing the type of creature being + * spawned * @deprecated In favour of {@link #getEntityType()}. */ @Deprecated @@ -64,7 +65,8 @@ public class CreatureSpawnEvent extends EntityEvent implements Cancellable { /** * Gets the reason for why the creature is being spawned. * - * @return A SpawnReason value detailing the reason for the creature being spawned + * @return A SpawnReason value detailing the reason for the creature being + * spawned */ public SpawnReason getSpawnReason() { return spawnReason; @@ -89,7 +91,8 @@ public class CreatureSpawnEvent extends EntityEvent implements Cancellable { */ NATURAL, /** - * When an entity spawns as a jockey of another entity (mostly spider jockeys) + * When an entity spawns as a jockey of another entity (mostly spider + * jockeys) */ JOCKEY, /** diff --git a/src/main/java/org/bukkit/event/entity/CreeperPowerEvent.java b/src/main/java/org/bukkit/event/entity/CreeperPowerEvent.java index ea3f0df0..b103a6ae 100644 --- a/src/main/java/org/bukkit/event/entity/CreeperPowerEvent.java +++ b/src/main/java/org/bukkit/event/entity/CreeperPowerEvent.java @@ -73,16 +73,19 @@ public class CreeperPowerEvent extends EntityEvent implements Cancellable { /** * Power change caused by a lightning bolt + * <p> * Powered state: true */ LIGHTNING, /** * Power change caused by something else (probably a plugin) + * <p> * Powered state: true */ SET_ON, /** * Power change caused by something else (probably a plugin) + * <p> * Powered state: false */ SET_OFF diff --git a/src/main/java/org/bukkit/event/entity/EntityBreakDoorEvent.java b/src/main/java/org/bukkit/event/entity/EntityBreakDoorEvent.java index a192dfe8..2cbbc697 100644 --- a/src/main/java/org/bukkit/event/entity/EntityBreakDoorEvent.java +++ b/src/main/java/org/bukkit/event/entity/EntityBreakDoorEvent.java @@ -8,7 +8,7 @@ import org.bukkit.entity.LivingEntity; /** * Called when an {@link Entity} breaks a door * <p> - * Canceling the event will cause the event to be delayed + * Cancelling the event will cause the event to be delayed */ public class EntityBreakDoorEvent extends EntityChangeBlockEvent { public EntityBreakDoorEvent(final LivingEntity entity, final Block targetBlock) { diff --git a/src/main/java/org/bukkit/event/entity/EntityChangeBlockEvent.java b/src/main/java/org/bukkit/event/entity/EntityChangeBlockEvent.java index 454393cf..41be9ca9 100644 --- a/src/main/java/org/bukkit/event/entity/EntityChangeBlockEvent.java +++ b/src/main/java/org/bukkit/event/entity/EntityChangeBlockEvent.java @@ -22,7 +22,8 @@ public class EntityChangeBlockEvent extends EntityEvent implements Cancellable { * @param what the LivingEntity causing the change * @param block the block (before the change) * @param to the future material being changed to - * @deprecated Provided as a backward compatibility before the data byte was provided, and type increased to all entities + * @deprecated Provided as a backward compatibility before the data byte + * was provided, and type increased to all entities */ @Deprecated public EntityChangeBlockEvent(final LivingEntity what, final Block block, final Material to) { diff --git a/src/main/java/org/bukkit/event/entity/EntityCombustEvent.java b/src/main/java/org/bukkit/event/entity/EntityCombustEvent.java index 4f9418dc..43c44829 100644 --- a/src/main/java/org/bukkit/event/entity/EntityCombustEvent.java +++ b/src/main/java/org/bukkit/event/entity/EntityCombustEvent.java @@ -29,7 +29,8 @@ public class EntityCombustEvent extends EntityEvent implements Cancellable { } /** - * @return the amount of time (in seconds) the combustee should be alight for + * @return the amount of time (in seconds) the combustee should be alight + * for */ public int getDuration() { return duration; @@ -38,7 +39,8 @@ public class EntityCombustEvent extends EntityEvent implements Cancellable { /** * The number of seconds the combustee should be alight for. * <p> - * This value will only ever increase the combustion time, not decrease existing combustion times. + * This value will only ever increase the combustion time, not decrease + * existing combustion times. * * @param duration the time in seconds to be alight for. */ diff --git a/src/main/java/org/bukkit/event/entity/EntityDamageEvent.java b/src/main/java/org/bukkit/event/entity/EntityDamageEvent.java index 799390bc..6e722d29 100644 --- a/src/main/java/org/bukkit/event/entity/EntityDamageEvent.java +++ b/src/main/java/org/bukkit/event/entity/EntityDamageEvent.java @@ -161,7 +161,8 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable { */ BLOCK_EXPLOSION, /** - * Damage caused by being in the area when an entity, such as a Creeper, explodes. + * Damage caused by being in the area when an entity, such as a + * Creeper, explodes. * <p> * Damage: variable */ @@ -215,7 +216,8 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable { */ FALLING_BLOCK, /** - * Damage caused in retaliation to another attack by the Thorns enchantment. + * Damage caused in retaliation to another attack by the Thorns + * enchantment. * <p> * Damage: 1-4 (Thorns) */ diff --git a/src/main/java/org/bukkit/event/entity/EntityDeathEvent.java b/src/main/java/org/bukkit/event/entity/EntityDeathEvent.java index d39596f6..ab9e81fd 100644 --- a/src/main/java/org/bukkit/event/entity/EntityDeathEvent.java +++ b/src/main/java/org/bukkit/event/entity/EntityDeathEvent.java @@ -31,8 +31,8 @@ public class EntityDeathEvent extends EntityEvent { /** * Gets how much EXP should be dropped from this death. * <p> - * This does not indicate how much EXP should be taken from the entity in question, - * merely how much should be created after its death. + * This does not indicate how much EXP should be taken from the entity in + * question, merely how much should be created after its death. * * @return Amount of EXP to drop. */ @@ -43,8 +43,8 @@ public class EntityDeathEvent extends EntityEvent { /** * Sets how much EXP should be dropped from this death. * <p> - * This does not indicate how much EXP should be taken from the entity in question, - * merely how much should be created after its death. + * This does not indicate how much EXP should be taken from the entity in + * question, merely how much should be created after its death. * * @param exp Amount of EXP to drop. */ diff --git a/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java b/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java index 13b802f7..287035d1 100644 --- a/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java +++ b/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java @@ -35,8 +35,8 @@ public class EntityExplodeEvent extends EntityEvent implements Cancellable { } /** - * Returns the list of blocks that would have been removed or were - * removed from the explosion event. + * Returns the list of blocks that would have been removed or were removed + * from the explosion event. * * @return All blown-up blocks */ @@ -46,8 +46,9 @@ public class EntityExplodeEvent extends EntityEvent implements Cancellable { /** * Returns the location where the explosion happened. - * It is not possible to get this value from the Entity as - * the Entity no longer exists in the world. + * <p> + * It is not possible to get this value from the Entity as the Entity no + * longer exists in the world. * * @return The location of the explosion */ diff --git a/src/main/java/org/bukkit/event/entity/EntityPortalExitEvent.java b/src/main/java/org/bukkit/event/entity/EntityPortalExitEvent.java index 657a4a0b..682fe590 100644 --- a/src/main/java/org/bukkit/event/entity/EntityPortalExitEvent.java +++ b/src/main/java/org/bukkit/event/entity/EntityPortalExitEvent.java @@ -8,8 +8,8 @@ import org.bukkit.util.Vector; /** * Called before an entity exits a portal. * <p> - * This event allows you to modify the velocity of the entity after they - * have successfully exeted the portal. + * This event allows you to modify the velocity of the entity after they have + * successfully exited the portal. */ public class EntityPortalExitEvent extends EntityTeleportEvent { private static final HandlerList handlers = new HandlerList(); @@ -23,7 +23,8 @@ public class EntityPortalExitEvent extends EntityTeleportEvent { } /** - * Gets a copy of the velocity that the entity has before entering the portal. + * Gets a copy of the velocity that the entity has before entering the + * portal. * * @return velocity of entity before entering portal */ @@ -32,7 +33,8 @@ public class EntityPortalExitEvent extends EntityTeleportEvent { } /** - * Gets a copy of the velocity that the entity will have after exiting the portal. + * Gets a copy of the velocity that the entity will have after exiting the + * portal. * * @return velocity of entity after exiting portal */ diff --git a/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java b/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java index d635a016..b4291b07 100644 --- a/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java +++ b/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java @@ -74,7 +74,8 @@ public class EntityRegainHealthEvent extends EntityEvent implements Cancellable /** * Gets the reason for why the entity is regaining health * - * @return A RegainReason detailing the reason for the entity regaining health + * @return A RegainReason detailing the reason for the entity regaining + * health */ public RegainReason getRegainReason() { return regainReason; @@ -95,11 +96,13 @@ public class EntityRegainHealthEvent extends EntityEvent implements Cancellable public enum RegainReason { /** - * When a player regains health from regenerating due to Peaceful mode (difficulty=0) + * When a player regains health from regenerating due to Peaceful mode + * (difficulty=0) */ REGEN, /** - * When a player regains health from regenerating due to their hunger being satisfied + * When a player regains health from regenerating due to their hunger + * being satisfied */ SATIATED, /** diff --git a/src/main/java/org/bukkit/event/entity/EntityShootBowEvent.java b/src/main/java/org/bukkit/event/entity/EntityShootBowEvent.java index 69afbacd..a631e2cb 100644 --- a/src/main/java/org/bukkit/event/entity/EntityShootBowEvent.java +++ b/src/main/java/org/bukkit/event/entity/EntityShootBowEvent.java @@ -30,7 +30,8 @@ public class EntityShootBowEvent extends EntityEvent implements Cancellable { } /** - * Gets the bow ItemStack used to fire the arrow; is null if the shooter is a skeleton + * Gets the bow ItemStack used to fire the arrow; is null if the shooter + * is a skeleton * * @return the bow involved in this event, or null */ diff --git a/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java b/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java index e57e05f5..2bcfbba7 100644 --- a/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java +++ b/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java @@ -38,8 +38,9 @@ public class EntityTargetEvent extends EntityEvent implements Cancellable { /** * Get the entity that this is targeting. - * This will be null in the case that the event is called when - * the mob forgets its target. + * <p> + * This will be null in the case that the event is called when the mob + * forgets its target. * * @return The entity */ @@ -49,12 +50,13 @@ public class EntityTargetEvent extends EntityEvent implements Cancellable { /** * Set the entity that you want the mob to target instead. + * <p> * It is possible to be null, null will cause the entity to be * target-less. * <p> - * This is different from cancelling the event. Cancelling the event - * will cause the entity to keep an original target, while setting to be - * null will cause the entity to be reset + * This is different from cancelling the event. Cancelling the event will + * cause the entity to keep an original target, while setting to be null + * will cause the entity to be reset. * * @param target The entity to target */ @@ -96,15 +98,19 @@ public class EntityTargetEvent extends EntityEvent implements Cancellable { PIG_ZOMBIE_TARGET, /** * When the target is forgotten for whatever reason. - * Currently only occurs in with spiders when there is a high brightness + * <p> + * Currently only occurs in with spiders when there is a high + * brightness. */ FORGOT_TARGET, /** - * When the target attacks the owner of the entity, so the entity targets it. + * When the target attacks the owner of the entity, so the entity + * targets it. */ TARGET_ATTACKED_OWNER, /** - * When the owner of the entity attacks the target attacks, so the entity targets it. + * When the owner of the entity attacks the target attacks, so the + * entity targets it. */ OWNER_ATTACKED_TARGET, /** @@ -116,7 +122,7 @@ public class EntityTargetEvent extends EntityEvent implements Cancellable { */ DEFEND_VILLAGE, /** - * For custom calls to the event + * For custom calls to the event. */ CUSTOM } diff --git a/src/main/java/org/bukkit/event/entity/EntityTargetLivingEntityEvent.java b/src/main/java/org/bukkit/event/entity/EntityTargetLivingEntityEvent.java index 6d445aa2..cd9aea1c 100644 --- a/src/main/java/org/bukkit/event/entity/EntityTargetLivingEntityEvent.java +++ b/src/main/java/org/bukkit/event/entity/EntityTargetLivingEntityEvent.java @@ -4,7 +4,8 @@ import org.bukkit.entity.Entity; import org.bukkit.entity.LivingEntity; /** - * Called when an Entity targets a {@link LivingEntity} and can only target LivingEntity's. + * Called when an Entity targets a {@link LivingEntity} and can only target + * LivingEntity's. */ public class EntityTargetLivingEntityEvent extends EntityTargetEvent{ public EntityTargetLivingEntityEvent(final Entity entity, final LivingEntity target, final TargetReason reason) { @@ -17,10 +18,11 @@ public class EntityTargetLivingEntityEvent extends EntityTargetEvent{ /** * Set the Entity that you want the mob to target. + * <p> * It is possible to be null, null will cause the entity to be * target-less. * <p> - * Must be a LivingEntity, or null + * Must be a LivingEntity, or null. * * @param target The entity to target */ diff --git a/src/main/java/org/bukkit/event/entity/EntityTeleportEvent.java b/src/main/java/org/bukkit/event/entity/EntityTeleportEvent.java index 378dba79..619f8d4f 100644 --- a/src/main/java/org/bukkit/event/entity/EntityTeleportEvent.java +++ b/src/main/java/org/bukkit/event/entity/EntityTeleportEvent.java @@ -6,8 +6,8 @@ import org.bukkit.event.Cancellable; import org.bukkit.event.HandlerList; /** - * Thrown when a non-player entity (such as an Enderman) tries to teleport from one - * location to another. + * Thrown when a non-player entity (such as an Enderman) tries to teleport + * from one location to another. */ public class EntityTeleportEvent extends EntityEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); diff --git a/src/main/java/org/bukkit/event/entity/ExpBottleEvent.java b/src/main/java/org/bukkit/event/entity/ExpBottleEvent.java index a1983ba8..4f64424e 100644 --- a/src/main/java/org/bukkit/event/entity/ExpBottleEvent.java +++ b/src/main/java/org/bukkit/event/entity/ExpBottleEvent.java @@ -1,73 +1,75 @@ -package org.bukkit.event.entity;
-
-import org.bukkit.entity.ThrownExpBottle;
-import org.bukkit.event.HandlerList;
-
-/**
- * Called when a ThrownExpBottle hits and releases experience.
- */
-public class ExpBottleEvent extends ProjectileHitEvent {
- private static final HandlerList handlers = new HandlerList();
- private int exp;
- private boolean showEffect = true;
-
- public ExpBottleEvent(final ThrownExpBottle bottle, final int exp) {
- super(bottle);
- this.exp = exp;
- }
-
- @Override
- public ThrownExpBottle getEntity() {
- return (ThrownExpBottle) entity;
- }
-
- /**
- * This method indicates if the particle effect should be shown.
- *
- * @return true if the effect will be shown, false otherwise
- */
- public boolean getShowEffect() {
- return this.showEffect;
- }
-
- /**
- * This method sets if the particle effect will be shown.
- * This does not change the experience created.
- *
- * @param showEffect
- * true indicates the effect will be shown,
- * false indicates no effect will be shown
- */
- public void setShowEffect(final boolean showEffect) {
- this.showEffect = showEffect;
- }
-
- /**
- * This method retrieves the amount of experience to be created.
- * The number indicates a total amount to be divided into orbs.
- *
- * @return the total amount of experience to be created
- */
- public int getExperience() {
- return exp;
- }
-
- /**
- * This method sets the amount of experience to be created.
- * The number indicates a total amount to be divided into orbs.
- *
- * @param exp the total amount of experience to be created
- */
- public void setExperience(final int exp) {
- this.exp = exp;
- }
-
- @Override
- public HandlerList getHandlers() {
- return handlers;
- }
-
- public static HandlerList getHandlerList() {
- return handlers;
- }
-}
+package org.bukkit.event.entity; + +import org.bukkit.entity.ThrownExpBottle; +import org.bukkit.event.HandlerList; + +/** + * Called when a ThrownExpBottle hits and releases experience. + */ +public class ExpBottleEvent extends ProjectileHitEvent { + private static final HandlerList handlers = new HandlerList(); + private int exp; + private boolean showEffect = true; + + public ExpBottleEvent(final ThrownExpBottle bottle, final int exp) { + super(bottle); + this.exp = exp; + } + + @Override + public ThrownExpBottle getEntity() { + return (ThrownExpBottle) entity; + } + + /** + * This method indicates if the particle effect should be shown. + * + * @return true if the effect will be shown, false otherwise + */ + public boolean getShowEffect() { + return this.showEffect; + } + + /** + * This method sets if the particle effect will be shown. + * <p> + * This does not change the experience created. + * + * @param showEffect true indicates the effect will be shown, false + * indicates no effect will be shown + */ + public void setShowEffect(final boolean showEffect) { + this.showEffect = showEffect; + } + + /** + * This method retrieves the amount of experience to be created. + * <p> + * The number indicates a total amount to be divided into orbs. + * + * @return the total amount of experience to be created + */ + public int getExperience() { + return exp; + } + + /** + * This method sets the amount of experience to be created. + * <p> + * The number indicates a total amount to be divided into orbs. + * + * @param exp the total amount of experience to be created + */ + public void setExperience(final int exp) { + this.exp = exp; + } + + @Override + public HandlerList getHandlers() { + return handlers; + } + + public static HandlerList getHandlerList() { + return handlers; + } +} diff --git a/src/main/java/org/bukkit/event/entity/FoodLevelChangeEvent.java b/src/main/java/org/bukkit/event/entity/FoodLevelChangeEvent.java index 826326f6..f6e24725 100644 --- a/src/main/java/org/bukkit/event/entity/FoodLevelChangeEvent.java +++ b/src/main/java/org/bukkit/event/entity/FoodLevelChangeEvent.java @@ -23,7 +23,8 @@ public class FoodLevelChangeEvent extends EntityEvent implements Cancellable { } /** - * Gets the resultant food level that the entity involved in this event should be set to. + * Gets the resultant food level that the entity involved in this event + * should be set to. * <p> * Where 20 is a full food bar and 0 is an empty one. * @@ -34,9 +35,11 @@ public class FoodLevelChangeEvent extends EntityEvent implements Cancellable { } /** - * Sets the resultant food level that the entity involved in this event should be set to + * Sets the resultant food level that the entity involved in this event + * should be set to * - * @param level the resultant food level that the entity involved in this event should be set to + * @param level the resultant food level that the entity involved in this + * event should be set to */ public void setFoodLevel(int level) { if (level > 20) level = 20; diff --git a/src/main/java/org/bukkit/event/entity/HorseJumpEvent.java b/src/main/java/org/bukkit/event/entity/HorseJumpEvent.java index 8533fe93..fad2468d 100644 --- a/src/main/java/org/bukkit/event/entity/HorseJumpEvent.java +++ b/src/main/java/org/bukkit/event/entity/HorseJumpEvent.java @@ -35,15 +35,15 @@ public class HorseJumpEvent extends EntityEvent implements Cancellable { * <p> * Power is a value that defines how much of the horse's jump strength * should be used for the jump. Power is effectively multiplied times - * the horse's jump strength to determine how high the jump is; - * 0 represents no jump strength while 1 represents full jump strength. + * the horse's jump strength to determine how high the jump is; 0 + * represents no jump strength while 1 represents full jump strength. * Setting power to a value above 1 will use additional jump strength * that the horse does not usually have. * <p> - * Power does not affect how high the horse is capable of jumping, - * only how much of its jumping capability will be used in this jump. - * To set the horse's overall jump strength, see - * {@link Horse#setJumpStrength(double)}. + * Power does not affect how high the horse is capable of jumping, only + * how much of its jumping capability will be used in this jump. To set + * the horse's overall jump strength, see {@link + * Horse#setJumpStrength(double)}. * * @return jump strength */ @@ -54,12 +54,12 @@ public class HorseJumpEvent extends EntityEvent implements Cancellable { /** * Sets the power of the jump. * <p> - * Jump power can be set to a value above 1.0 which will increase - * the strength of this jump above the horse's actual jump strength. + * Jump power can be set to a value above 1.0 which will increase the + * strength of this jump above the horse's actual jump strength. * <p> - * Setting the jump power to 0 will result in the jump animation - * still playing, but the horse not leaving the ground. Only - * canceling this event will result in no jump animation at all. + * Setting the jump power to 0 will result in the jump animation still + * playing, but the horse not leaving the ground. Only canceling this + * event will result in no jump animation at all. * * @param power power of the jump */ diff --git a/src/main/java/org/bukkit/event/entity/PigZapEvent.java b/src/main/java/org/bukkit/event/entity/PigZapEvent.java index 47601762..aa80ebf1 100644 --- a/src/main/java/org/bukkit/event/entity/PigZapEvent.java +++ b/src/main/java/org/bukkit/event/entity/PigZapEvent.java @@ -44,8 +44,8 @@ public class PigZapEvent extends EntityEvent implements Cancellable { } /** - * Gets the zombie pig that will replace the pig, - * provided the event is not cancelled first. + * Gets the zombie pig that will replace the pig, provided the event is + * not cancelled first. * * @return resulting entity */ diff --git a/src/main/java/org/bukkit/event/entity/PotionSplashEvent.java b/src/main/java/org/bukkit/event/entity/PotionSplashEvent.java index 2065ae4d..b9840de1 100644 --- a/src/main/java/org/bukkit/event/entity/PotionSplashEvent.java +++ b/src/main/java/org/bukkit/event/entity/PotionSplashEvent.java @@ -1,93 +1,94 @@ -package org.bukkit.event.entity;
-
-import java.util.ArrayList;
-import java.util.Collection;
-import java.util.Map;
-
-import org.apache.commons.lang.Validate;
-import org.bukkit.entity.LivingEntity;
-import org.bukkit.entity.ThrownPotion;
-import org.bukkit.event.Cancellable;
-import org.bukkit.event.HandlerList;
-
-/**
- * Called when a splash potion hits an area
- */
-public class PotionSplashEvent extends ProjectileHitEvent implements Cancellable {
- private static final HandlerList handlers = new HandlerList();
- private boolean cancelled;
- private final Map<LivingEntity, Double> affectedEntities;
-
- public PotionSplashEvent(final ThrownPotion potion, final Map<LivingEntity, Double> affectedEntities) {
- super(potion);
-
- this.affectedEntities = affectedEntities;
- }
-
- @Override
- public ThrownPotion getEntity() {
- return (ThrownPotion) entity;
- }
-
- /**
- * Gets the potion which caused this event
- *
- * @return The thrown potion entity
- */
- public ThrownPotion getPotion() {
- return (ThrownPotion) getEntity();
- }
-
- /**
- * Retrieves a list of all effected entities
- *
- * @return A fresh copy of the affected entity list
- */
- public Collection<LivingEntity> getAffectedEntities() {
- return new ArrayList<LivingEntity>(affectedEntities.keySet());
- }
-
- /**
- * Gets the intensity of the potion's effects for given entity;
- * This depends on the distance to the impact center
- *
- * @param entity Which entity to get intensity for
- * @return intensity relative to maximum effect; 0.0: not affected; 1.0: fully hit by potion effects
- */
- public double getIntensity(LivingEntity entity) {
- Double intensity = affectedEntities.get(entity);
- return intensity != null ? intensity : 0.0;
- }
-
- /**
- * Overwrites the intensity for a given entity
- *
- * @param entity For which entity to define a new intensity
- * @param intensity relative to maximum effect
- */
- public void setIntensity(LivingEntity entity, double intensity) {
- Validate.notNull(entity, "You must specify a valid entity.");
- if (intensity <= 0.0) {
- affectedEntities.remove(entity);
- } else {
- affectedEntities.put(entity, Math.min(intensity, 1.0));
- }
- }
-
- public boolean isCancelled() {
- return cancelled;
- }
-
- public void setCancelled(boolean cancel) {
- cancelled = cancel;
- }
-
- @Override
- public HandlerList getHandlers() {
- return handlers;
- }
-
- public static HandlerList getHandlerList() {
- return handlers;
- }
-}
+package org.bukkit.event.entity; + +import java.util.ArrayList; +import java.util.Collection; +import java.util.Map; + +import org.apache.commons.lang.Validate; +import org.bukkit.entity.LivingEntity; +import org.bukkit.entity.ThrownPotion; +import org.bukkit.event.Cancellable; +import org.bukkit.event.HandlerList; + +/** + * Called when a splash potion hits an area + */ +public class PotionSplashEvent extends ProjectileHitEvent implements Cancellable { + private static final HandlerList handlers = new HandlerList(); + private boolean cancelled; + private final Map<LivingEntity, Double> affectedEntities; + + public PotionSplashEvent(final ThrownPotion potion, final Map<LivingEntity, Double> affectedEntities) { + super(potion); + + this.affectedEntities = affectedEntities; + } + + @Override + public ThrownPotion getEntity() { + return (ThrownPotion) entity; + } + + /** + * Gets the potion which caused this event + * + * @return The thrown potion entity + */ + public ThrownPotion getPotion() { + return (ThrownPotion) getEntity(); + } + + /** + * Retrieves a list of all effected entities + * + * @return A fresh copy of the affected entity list + */ + public Collection<LivingEntity> getAffectedEntities() { + return new ArrayList<LivingEntity>(affectedEntities.keySet()); + } + + /** + * Gets the intensity of the potion's effects for given entity; This + * depends on the distance to the impact center + * + * @param entity Which entity to get intensity for + * @return intensity relative to maximum effect; 0.0: not affected; 1.0: + * fully hit by potion effects + */ + public double getIntensity(LivingEntity entity) { + Double intensity = affectedEntities.get(entity); + return intensity != null ? intensity : 0.0; + } + + /** + * Overwrites the intensity for a given entity + * + * @param entity For which entity to define a new intensity + * @param intensity relative to maximum effect + */ + public void setIntensity(LivingEntity entity, double intensity) { + Validate.notNull(entity, "You must specify a valid entity."); + if (intensity <= 0.0) { + affectedEntities.remove(entity); + } else { + affectedEntities.put(entity, Math.min(intensity, 1.0)); + } + } + + public boolean isCancelled() { + return cancelled; + } + + public void setCancelled(boolean cancel) { + cancelled = cancel; + } + + @Override + public HandlerList getHandlers() { + return handlers; + } + + public static HandlerList getHandlerList() { + return handlers; + } +} diff --git a/src/main/java/org/bukkit/event/entity/SheepRegrowWoolEvent.java b/src/main/java/org/bukkit/event/entity/SheepRegrowWoolEvent.java index 02d8a2e0..e836f7b3 100644 --- a/src/main/java/org/bukkit/event/entity/SheepRegrowWoolEvent.java +++ b/src/main/java/org/bukkit/event/entity/SheepRegrowWoolEvent.java @@ -1,41 +1,41 @@ -package org.bukkit.event.entity;
-
-import org.bukkit.entity.Sheep;
-import org.bukkit.event.Cancellable;
-import org.bukkit.event.HandlerList;
-
-/**
- * Called when a sheep regrows its wool
- */
-public class SheepRegrowWoolEvent extends EntityEvent implements Cancellable {
- private static final HandlerList handlers = new HandlerList();
- private boolean cancel;
-
- public SheepRegrowWoolEvent(final Sheep sheep) {
- super(sheep);
- this.cancel = false;
- }
-
- public boolean isCancelled() {
- return cancel;
- }
-
- public void setCancelled(boolean cancel) {
- this.cancel = cancel;
- }
-
- @Override
- public Sheep getEntity() {
- return (Sheep) entity;
- }
-
- @Override
- public HandlerList getHandlers() {
- return handlers;
- }
-
- public static HandlerList getHandlerList() {
- return handlers;
- }
-
-}
+package org.bukkit.event.entity; + +import org.bukkit.entity.Sheep; +import org.bukkit.event.Cancellable; +import org.bukkit.event.HandlerList; + +/** + * Called when a sheep regrows its wool + */ +public class SheepRegrowWoolEvent extends EntityEvent implements Cancellable { + private static final HandlerList handlers = new HandlerList(); + private boolean cancel; + + public SheepRegrowWoolEvent(final Sheep sheep) { + super(sheep); + this.cancel = false; + } + + public boolean isCancelled() { + return cancel; + } + + public void setCancelled(boolean cancel) { + this.cancel = cancel; + } + + @Override + public Sheep getEntity() { + return (Sheep) entity; + } + + @Override + public HandlerList getHandlers() { + return handlers; + } + + public static HandlerList getHandlerList() { + return handlers; + } + +} diff --git a/src/main/java/org/bukkit/event/inventory/BrewEvent.java b/src/main/java/org/bukkit/event/inventory/BrewEvent.java index 6e0c0284..2295c2d9 100644 --- a/src/main/java/org/bukkit/event/inventory/BrewEvent.java +++ b/src/main/java/org/bukkit/event/inventory/BrewEvent.java @@ -7,7 +7,8 @@ import org.bukkit.event.block.BlockEvent; import org.bukkit.inventory.BrewerInventory; /** - * Called when the brewing of the contents inside the Brewing Stand is complete. + * Called when the brewing of the contents inside the Brewing Stand is + * complete. */ public class BrewEvent extends BlockEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); diff --git a/src/main/java/org/bukkit/event/inventory/ClickType.java b/src/main/java/org/bukkit/event/inventory/ClickType.java index c9e447fa..a7440aac 100644 --- a/src/main/java/org/bukkit/event/inventory/ClickType.java +++ b/src/main/java/org/bukkit/event/inventory/ClickType.java @@ -22,13 +22,11 @@ public enum ClickType { */ SHIFT_RIGHT, /** - * Clicking the left mouse button on the grey area around the - * inventory. + * Clicking the left mouse button on the grey area around the inventory. */ WINDOW_BORDER_LEFT, /** - * Clicking the right mouse button on the grey area around the - * inventory. + * Clicking the right mouse button on the grey area around the inventory. */ WINDOW_BORDER_RIGHT, /** @@ -57,8 +55,9 @@ public enum ClickType { CREATIVE, /** * A type of inventory manipulation not yet recognized by Bukkit. - * This is only for transitional purposes on a new Minecraft update, - * and should never be relied upon. + * <p> + * This is only for transitional purposes on a new Minecraft update, and + * should never be relied upon. * <p> * Any ClickType.UNKNOWN is called on a best-effort basis. */ diff --git a/src/main/java/org/bukkit/event/inventory/DragType.java b/src/main/java/org/bukkit/event/inventory/DragType.java index 9000faf1..72c2bed9 100644 --- a/src/main/java/org/bukkit/event/inventory/DragType.java +++ b/src/main/java/org/bukkit/event/inventory/DragType.java @@ -1,18 +1,17 @@ -package org.bukkit.event.inventory;
-
-/**
- * Represents the effect of a drag that will be applied to an Inventory in an
- * InventoryDragEvent.
- */
-public enum DragType {
- /**
- * One item from the cursor is placed in each selected slot.
- */
- SINGLE,
- /**
- * The cursor is split evenly across all selected slots, not to
- * exceed the Material's max stack size, with the remainder going to
- * the cursor.
- */
- EVEN,
-}
+package org.bukkit.event.inventory; + +/** + * Represents the effect of a drag that will be applied to an Inventory in an + * InventoryDragEvent. + */ +public enum DragType { + /** + * One item from the cursor is placed in each selected slot. + */ + SINGLE, + /** + * The cursor is split evenly across all selected slots, not to exceed the + * Material's max stack size, with the remainder going to the cursor. + */ + EVEN, +} diff --git a/src/main/java/org/bukkit/event/inventory/InventoryAction.java b/src/main/java/org/bukkit/event/inventory/InventoryAction.java index dbdbe26c..a7bc694b 100644 --- a/src/main/java/org/bukkit/event/inventory/InventoryAction.java +++ b/src/main/java/org/bukkit/event/inventory/InventoryAction.java @@ -8,9 +8,8 @@ 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. + * 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. */ NOTHING, /** @@ -67,8 +66,8 @@ public enum InventoryAction { */ MOVE_TO_OTHER_INVENTORY, /** - * The clicked item is moved to the hotbar, and the item currently - * there is re-added to the player's inventory. + * The clicked item is moved to the hotbar, and the item currently there + * is re-added to the player's inventory. */ HOTBAR_MOVE_AND_READD, /** @@ -80,8 +79,8 @@ public enum InventoryAction { */ CLONE_STACK, /** - * The inventory is searched for the same material, and they are put - * on the cursor up to {@link org.bukkit.Material#getMaxStackSize()}. + * The inventory is searched for the same material, and they are put on + * the cursor up to {@link org.bukkit.Material#getMaxStackSize()}. */ COLLECT_TO_CURSOR, /** diff --git a/src/main/java/org/bukkit/event/inventory/InventoryEvent.java b/src/main/java/org/bukkit/event/inventory/InventoryEvent.java index abca85c7..973c392e 100644 --- a/src/main/java/org/bukkit/event/inventory/InventoryEvent.java +++ b/src/main/java/org/bukkit/event/inventory/InventoryEvent.java @@ -30,7 +30,8 @@ public class InventoryEvent extends Event { } /** - * Gets the list of players viewing the primary (upper) inventory involved in this event + * Gets the list of players viewing the primary (upper) inventory involved + * in this event * * @return A list of people viewing. */ diff --git a/src/main/java/org/bukkit/event/inventory/InventoryMoveItemEvent.java b/src/main/java/org/bukkit/event/inventory/InventoryMoveItemEvent.java index ba669684..06ec99ae 100644 --- a/src/main/java/org/bukkit/event/inventory/InventoryMoveItemEvent.java +++ b/src/main/java/org/bukkit/event/inventory/InventoryMoveItemEvent.java @@ -8,8 +8,8 @@ import org.bukkit.inventory.Inventory; import org.bukkit.inventory.ItemStack; /** - * Called when some entity or block (e.g. hopper) tries to move items - * directly from one inventory to another. + * Called when some entity or block (e.g. hopper) tries to move items directly + * from one inventory to another. * <p> * When this event is called, the initiator may already have removed the item * from the source inventory and is ready to move it into the destination @@ -18,11 +18,10 @@ import org.bukkit.inventory.ItemStack; * If this event is cancelled, the items will be returned to the source * inventory, if needed. * <p> - * If this event is not cancelled, the initiator will try to put the - * ItemStack into the destination inventory. If this is not possible and the - * ItemStack has not been modified, the source inventory slot will be - * restored to its former state. Otherwise any additional items will be - * discarded. + * If this event is not cancelled, the initiator will try to put the ItemStack + * into the destination inventory. If this is not possible and the ItemStack + * has not been modified, the source inventory slot will be restored to its + * former state. Otherwise any additional items will be discarded. */ public class InventoryMoveItemEvent extends Event implements Cancellable { private static final HandlerList handlers = new HandlerList(); @@ -50,8 +49,8 @@ public class InventoryMoveItemEvent extends Event implements Cancellable { } /** - * Gets the ItemStack being moved; if modified, the original item will - * not be removed from the source inventory. + * Gets the ItemStack being moved; if modified, the original item will not + * be removed from the source inventory. * * @return ItemStack */ @@ -81,8 +80,8 @@ public class InventoryMoveItemEvent extends Event implements Cancellable { } /** - * Gets the Inventory that initiated the transfer. This will always - * be either the destination or source Inventory. + * Gets the Inventory that initiated the transfer. This will always be + * either the destination or source Inventory. * * @return Inventory that initiated the transfer */ diff --git a/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java b/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java index e66a78b3..c3570aae 100644 --- a/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java +++ b/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java @@ -30,7 +30,8 @@ public class InventoryOpenEvent extends InventoryEvent implements 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. * <p> - * If an inventory open event is cancelled, the inventory screen will not show. + * If an inventory open event is cancelled, the inventory screen will not + * show. * * @return true if this event is cancelled */ @@ -42,7 +43,8 @@ public class InventoryOpenEvent extends InventoryEvent implements Cancellable { * Sets the cancellation state of this event. A cancelled event will not * be executed in the server, but will still pass to other plugins. * <p> - * If an inventory open event is cancelled, the inventory screen will not show. + * If an inventory open event is cancelled, the inventory screen will not + * show. * * @param cancel true if you wish to cancel this event */ diff --git a/src/main/java/org/bukkit/event/inventory/InventoryType.java b/src/main/java/org/bukkit/event/inventory/InventoryType.java index 06cabcd5..b83580a4 100644 --- a/src/main/java/org/bukkit/event/inventory/InventoryType.java +++ b/src/main/java/org/bukkit/event/inventory/InventoryType.java @@ -3,7 +3,8 @@ package org.bukkit.event.inventory; public enum InventoryType { /** - * A chest inventory, with 0, 9, 18, 27, 36, 45, or 54 slots of type CONTAINER. + * A chest inventory, with 0, 9, 18, 27, 36, 45, or 54 slots of type + * CONTAINER. */ CHEST(27,"Chest"), /** @@ -15,7 +16,8 @@ public enum InventoryType { */ DROPPER(9, "Dropper"), /** - * A furnace inventory, with a RESULT slot, a CRAFTING slot, and a FUEL slot. + * A furnace inventory, with a RESULT slot, a CRAFTING slot, and a FUEL + * slot. */ FURNACE(3,"Furnace"), /** @@ -23,12 +25,13 @@ public enum InventoryType { */ WORKBENCH(10,"Crafting"), /** - * A player's crafting inventory, with 4 CRAFTING slots and a RESULT slot. Also implies that the - * 4 ARMOR slots are accessible. + * A player's crafting inventory, with 4 CRAFTING slots and a RESULT slot. + * Also implies that the 4 ARMOR slots are accessible. */ CRAFTING(5,"Crafting"), /** - * An enchantment table inventory, with one CRAFTING slot and three enchanting buttons. + * An enchantment table inventory, with one CRAFTING slot and three + * enchanting buttons. */ ENCHANTING(1,"Enchanting"), /** @@ -36,13 +39,14 @@ public enum InventoryType { */ BREWING(4,"Brewing"), /** - * A player's inventory, with 9 QUICKBAR slots, 27 CONTAINER slots, and 4 ARMOR slots. The - * ARMOUR slots may not be visible to the player, though. + * A player's inventory, with 9 QUICKBAR slots, 27 CONTAINER slots, and 4 + * ARMOR slots. The ARMOUR slots may not be visible to the player, though. */ PLAYER(36,"Player"), /** - * The creative mode inventory, with only 9 QUICKBAR slots and nothing else. (The actual - * creative interface with the items is client-side and cannot be altered by the server.) + * The creative mode inventory, with only 9 QUICKBAR slots and nothing + * else. (The actual creative interface with the items is client-side and + * cannot be altered by the server.) */ CREATIVE(9,"Creative"), /** @@ -89,8 +93,9 @@ public enum InventoryType { */ RESULT, /** - * A slot in the crafting matrix, or the input slot in a furnace inventory, - * the potion slot in the brewing stand, or the enchanting slot. + * A slot in the crafting matrix, or the input slot in a furnace + * inventory, the potion slot in the brewing stand, or the enchanting + * slot. */ CRAFTING, /** @@ -98,8 +103,8 @@ public enum InventoryType { */ ARMOR, /** - * A regular slot in the container or the player's inventory; anything not covered - * by the other enum values. + * A regular slot in the container or the player's inventory; anything + * not covered by the other enum values. */ CONTAINER, /** @@ -111,7 +116,8 @@ public enum InventoryType { */ OUTSIDE, /** - * The fuel slot in a furnace inventory, or the ingredient slot in a brewing stand inventory. + * The fuel slot in a furnace inventory, or the ingredient slot in a + * brewing stand inventory. */ FUEL; } diff --git a/src/main/java/org/bukkit/event/inventory/PrepareItemCraftEvent.java b/src/main/java/org/bukkit/event/inventory/PrepareItemCraftEvent.java index 91474b0d..57311904 100644 --- a/src/main/java/org/bukkit/event/inventory/PrepareItemCraftEvent.java +++ b/src/main/java/org/bukkit/event/inventory/PrepareItemCraftEvent.java @@ -17,8 +17,9 @@ public class PrepareItemCraftEvent extends InventoryEvent { } /** - * Get the recipe that has been formed. If this event was triggered by a tool repair, this - * will be a temporary shapeless recipe representing the repair. + * Get the recipe that has been formed. If this event was triggered by a + * tool repair, this will be a temporary shapeless recipe representing the + * repair. * * @return The recipe being crafted. */ @@ -35,7 +36,8 @@ public class PrepareItemCraftEvent extends InventoryEvent { } /** - * Check if this event was triggered by a tool repair operation rather than a crafting recipe. + * Check if this event was triggered by a tool repair operation rather + * than a crafting recipe. * * @return True if this is a repair. */ diff --git a/src/main/java/org/bukkit/event/painting/PaintingBreakByEntityEvent.java b/src/main/java/org/bukkit/event/painting/PaintingBreakByEntityEvent.java index 91aa8f2f..1dc49873 100644 --- a/src/main/java/org/bukkit/event/painting/PaintingBreakByEntityEvent.java +++ b/src/main/java/org/bukkit/event/painting/PaintingBreakByEntityEvent.java @@ -6,7 +6,9 @@ import org.bukkit.entity.Painting; /** * Triggered when a painting is removed by an entity - * @deprecated Use {@link org.bukkit.event.hanging.HangingBreakByEntityEvent} instead. + * + * @deprecated Use {@link org.bukkit.event.hanging.HangingBreakByEntityEvent} + * instead. */ @Deprecated @Warning(reason="This event has been replaced by HangingBreakByEntityEvent") diff --git a/src/main/java/org/bukkit/event/painting/PaintingBreakEvent.java b/src/main/java/org/bukkit/event/painting/PaintingBreakEvent.java index e822d15c..3e27c69e 100644 --- a/src/main/java/org/bukkit/event/painting/PaintingBreakEvent.java +++ b/src/main/java/org/bukkit/event/painting/PaintingBreakEvent.java @@ -7,6 +7,7 @@ import org.bukkit.event.HandlerList; /** * Triggered when a painting is removed + * * @deprecated Use {@link org.bukkit.event.hanging.HangingBreakEvent} instead. */ @Deprecated diff --git a/src/main/java/org/bukkit/event/painting/PaintingEvent.java b/src/main/java/org/bukkit/event/painting/PaintingEvent.java index f942bb4d..3a51348e 100644 --- a/src/main/java/org/bukkit/event/painting/PaintingEvent.java +++ b/src/main/java/org/bukkit/event/painting/PaintingEvent.java @@ -6,6 +6,7 @@ import org.bukkit.event.Event; /** * Represents a painting-related event. + * * @deprecated Use {@link org.bukkit.event.hanging.HangingEvent} instead. */ @Deprecated diff --git a/src/main/java/org/bukkit/event/painting/PaintingPlaceEvent.java b/src/main/java/org/bukkit/event/painting/PaintingPlaceEvent.java index 914f9a3a..3250b292 100644 --- a/src/main/java/org/bukkit/event/painting/PaintingPlaceEvent.java +++ b/src/main/java/org/bukkit/event/painting/PaintingPlaceEvent.java @@ -10,6 +10,7 @@ import org.bukkit.event.HandlerList; /** * Triggered when a painting is created in the world + * * @deprecated Use {@link org.bukkit.event.hanging.HangingPlaceEvent} instead. */ @Deprecated @@ -49,7 +50,8 @@ public class PaintingPlaceEvent extends PaintingEvent implements Cancellable { /** * Returns the face of the block that the painting was placed on * - * @return BlockFace returns the face of the block the painting was placed on + * @return BlockFace returns the face of the block the painting was placed + * on */ public BlockFace getBlockFace() { return blockFace; diff --git a/src/main/java/org/bukkit/event/player/AsyncPlayerChatEvent.java b/src/main/java/org/bukkit/event/player/AsyncPlayerChatEvent.java index 916783f7..e728d44b 100644 --- a/src/main/java/org/bukkit/event/player/AsyncPlayerChatEvent.java +++ b/src/main/java/org/bukkit/event/player/AsyncPlayerChatEvent.java @@ -8,14 +8,20 @@ import org.bukkit.event.Cancellable; import org.bukkit.event.HandlerList; /** - * This event will sometimes fire synchronously, depending on how it was triggered. - * The constructor provides a boolean to indicate if the event was fired synchronously or asynchronously. - * When asynchronous, this event can be called from any thread, but the main thread, and has limited access to the API.<br> - * <br> - * If a player is the direct cause of this event by incoming packet, this event will be asynchronous. - * If a plugin triggers this event by compelling a player to chat, this event will be synchronous.<br> - * <br> - * <b>Care should be taken to check {@link #isAsynchronous()} and treat the event appropriately.</b> + * This event will sometimes fire synchronously, depending on how it was + * triggered. + * <p> + * The constructor provides a boolean to indicate if the event was fired + * synchronously or asynchronously. When asynchronous, this event can be + * called from any thread, but the main thread, and has limited access to the + * API. + * <p> + * If a player is the direct cause of this event by incoming packet, this + * event will be asynchronous. If a plugin triggers this event by compelling a + * player to chat, this event will be synchronous. + * <p> + * Care should be taken to check {@link #isAsynchronous()} and treat the event + * appropriately. */ public class AsyncPlayerChatEvent extends PlayerEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); @@ -29,7 +35,8 @@ public class AsyncPlayerChatEvent extends PlayerEvent implements Cancellable { * @param async This changes the event to a synchronous state. * @param who the chat sender * @param message the message sent - * @param players the players to receive the message. This may be a lazy or unmodifiable collection. + * @param players the players to receive the message. This may be a lazy + * or unmodifiable collection. */ public AsyncPlayerChatEvent(final boolean async, final Player who, final String message, final Set<Player> players) { super(who, async); @@ -38,7 +45,8 @@ public class AsyncPlayerChatEvent extends PlayerEvent implements Cancellable { } /** - * Gets the message that the player is attempting to send. This message will be used with {@link #getFormat()}. + * Gets the message that the player is attempting to send. This message + * will be used with {@link #getFormat()}. * * @return Message the player is attempting to send */ @@ -47,7 +55,8 @@ public class AsyncPlayerChatEvent extends PlayerEvent implements Cancellable { } /** - * Sets the message that the player will send. This message will be used with {@link #getFormat()}. + * Sets the message that the player will send. This message will be used + * with {@link #getFormat()}. * * @param message New message that the player will send */ @@ -57,9 +66,13 @@ public class AsyncPlayerChatEvent extends PlayerEvent implements Cancellable { /** * Gets the format to use to display this chat message. - * When this event finishes execution, the first format parameter is the {@link Player#getDisplayName()} and the second parameter is {@link #getMessage()} + * <p> + * When this event finishes execution, the first format parameter is the + * {@link Player#getDisplayName()} and the second parameter is {@link + * #getMessage()} * - * @return {@link String#format(String, Object...)} compatible format string + * @return {@link String#format(String, Object...)} compatible format + * string */ public String getFormat() { return format; @@ -67,10 +80,15 @@ public class AsyncPlayerChatEvent extends PlayerEvent implements Cancellable { /** * Sets the format to use to display this chat message. - * When this event finishes execution, the first format parameter is the {@link Player#getDisplayName()} and the second parameter is {@link #getMessage()} + * <p> + * When this event finishes execution, the first format parameter is the + * {@link Player#getDisplayName()} and the second parameter is {@link + * #getMessage()} * - * @param format {@link String#format(String, Object...)} compatible format string - * @throws IllegalFormatException if the underlying API throws the exception + * @param format {@link String#format(String, Object...)} compatible + * format string + * @throws IllegalFormatException if the underlying API throws the + * exception * @throws NullPointerException if format is null * @see String#format(String, Object...) */ @@ -88,10 +106,14 @@ public class AsyncPlayerChatEvent extends PlayerEvent implements Cancellable { /** * Gets a set of recipients that this chat message will be displayed to. - * The set returned is not guaranteed to be mutable and may auto-populate on access. - * Any listener accessing the returned set should be aware that it may reduce performance for a lazy set implementation.<br> - * <br> - * <b>Listeners should be aware that modifying the list may throw {@link UnsupportedOperationException} if the event caller provides an unmodifiable set.</b> + * <p> + * The set returned is not guaranteed to be mutable and may auto-populate + * on access. Any listener accessing the returned set should be aware that + * it may reduce performance for a lazy set implementation. + * <p> + * Listeners should be aware that modifying the list may throw {@link + * UnsupportedOperationException} if the event caller provides an + * unmodifiable set. * * @return All Players who will see this chat message */ diff --git a/src/main/java/org/bukkit/event/player/AsyncPlayerPreLoginEvent.java b/src/main/java/org/bukkit/event/player/AsyncPlayerPreLoginEvent.java index 4e4b3a27..02b373ce 100644 --- a/src/main/java/org/bukkit/event/player/AsyncPlayerPreLoginEvent.java +++ b/src/main/java/org/bukkit/event/player/AsyncPlayerPreLoginEvent.java @@ -6,7 +6,8 @@ import org.bukkit.event.Event; import org.bukkit.event.HandlerList; /** - * Stores details for players attempting to log in.<br> + * Stores details for players attempting to log in. + * <p> * This event is asynchronous, and not run using main thread. */ public class AsyncPlayerPreLoginEvent extends Event { @@ -37,7 +38,8 @@ public class AsyncPlayerPreLoginEvent extends Event { * Gets the current result of the login, as an enum * * @return Current Result of the login - * @deprecated This method uses a deprecated enum from {@link PlayerPreLoginEvent} + * @deprecated This method uses a deprecated enum from {@link + * PlayerPreLoginEvent} * @see #getLoginResult() */ @Deprecated @@ -58,7 +60,8 @@ public class AsyncPlayerPreLoginEvent extends Event { * Sets the new result of the login, as an enum * * @param result New result to set - * @deprecated This method uses a deprecated enum from {@link PlayerPreLoginEvent} + * @deprecated This method uses a deprecated enum from {@link + * PlayerPreLoginEvent} * @see #setLoginResult(Result) */ @Deprecated @@ -67,7 +70,8 @@ public class AsyncPlayerPreLoginEvent extends Event { } /** - * Gets the current kick message that will be used if getResult() != Result.ALLOWED + * Gets the current kick message that will be used if getResult() != + * Result.ALLOWED * * @return Current kick message */ @@ -108,7 +112,8 @@ public class AsyncPlayerPreLoginEvent extends Event { * * @param result New result for disallowing the player * @param message Kick message to display to the user - * @deprecated This method uses a deprecated enum from {@link PlayerPreLoginEvent} + * @deprecated This method uses a deprecated enum from {@link + * PlayerPreLoginEvent} * @see #disallow(Result, String) */ @Deprecated @@ -162,7 +167,8 @@ public class AsyncPlayerPreLoginEvent extends Event { */ KICK_BANNED, /** - * The player is not allowed to log in, due to them not being on the white list + * The player is not allowed to log in, due to them not being on the + * white list */ KICK_WHITELIST, /** diff --git a/src/main/java/org/bukkit/event/player/PlayerChannelEvent.java b/src/main/java/org/bukkit/event/player/PlayerChannelEvent.java index 270314e8..054efbc3 100644 --- a/src/main/java/org/bukkit/event/player/PlayerChannelEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerChannelEvent.java @@ -1,30 +1,31 @@ -package org.bukkit.event.player;
-
-import org.bukkit.entity.Player;
-import org.bukkit.event.HandlerList;
-
-/**
- * This event is called after a player registers or unregisters a new plugin channel.
- */
-public abstract class PlayerChannelEvent extends PlayerEvent {
- private static final HandlerList handlers = new HandlerList();
- private final String channel;
-
- public PlayerChannelEvent(final Player player, final String channel) {
- super(player);
- this.channel = channel;
- }
-
- public final String getChannel() {
- return channel;
- }
-
- @Override
- public HandlerList getHandlers() {
- return handlers;
- }
-
- public static HandlerList getHandlerList() {
- return handlers;
- }
-}
+package org.bukkit.event.player; + +import org.bukkit.entity.Player; +import org.bukkit.event.HandlerList; + +/** + * This event is called after a player registers or unregisters a new plugin + * channel. + */ +public abstract class PlayerChannelEvent extends PlayerEvent { + private static final HandlerList handlers = new HandlerList(); + private final String channel; + + public PlayerChannelEvent(final Player player, final String channel) { + super(player); + this.channel = channel; + } + + public final String getChannel() { + return channel; + } + + @Override + public HandlerList getHandlers() { + return handlers; + } + + public static HandlerList getHandlerList() { + return handlers; + } +} diff --git a/src/main/java/org/bukkit/event/player/PlayerChatEvent.java b/src/main/java/org/bukkit/event/player/PlayerChatEvent.java index 4872030d..b48ea360 100644 --- a/src/main/java/org/bukkit/event/player/PlayerChatEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerChatEvent.java @@ -12,10 +12,13 @@ import org.bukkit.event.HandlerList; /** * Holds information for player chat and commands - * @deprecated This event will fire from the main thread and allows the use of all of the Bukkit API, unlike the {@link AsyncPlayerChatEvent}.<br> - * <br> - * Listening to this event forces chat to wait for the main thread which causes delays for chat.<br> - * {@link AsyncPlayerChatEvent} is the encouraged alternative for thread safe implementations. + * + * @deprecated This event will fire from the main thread and allows the use of + * all of the Bukkit API, unlike the {@link AsyncPlayerChatEvent}. + * <p> + * Listening to this event forces chat to wait for the main thread which + * causes delays for chat. {@link AsyncPlayerChatEvent} is the encouraged + * alternative for thread safe implementations. */ @Deprecated @Warning(reason="Listening to this event forces chat to wait for the main thread, delaying chat messages.") diff --git a/src/main/java/org/bukkit/event/player/PlayerChatTabCompleteEvent.java b/src/main/java/org/bukkit/event/player/PlayerChatTabCompleteEvent.java index 761f7b11..7241a9b4 100644 --- a/src/main/java/org/bukkit/event/player/PlayerChatTabCompleteEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerChatTabCompleteEvent.java @@ -40,7 +40,9 @@ public class PlayerChatTabCompleteEvent extends PlayerEvent { /** * Gets the last 'token' of the message being tab-completed. - * The token is the substring starting with the character after the last space in the message. + * <p> + * The token is the substring starting with the character after the last + * space in the message. * * @return The last token for the chat message */ diff --git a/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java b/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java index 5fbdc145..7f3cae67 100644 --- a/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java @@ -75,7 +75,9 @@ public class PlayerCommandPreprocessEvent extends PlayerEvent implements Cancell /** * Gets the command that the player is attempting to send. - * All commands begin with a special character; implementations do not consider the first character when executing the content. + * <p> + * All commands begin with a special character; implementations do not + * consider the first character when executing the content. * * @return Message the player is attempting to send */ @@ -85,7 +87,9 @@ public class PlayerCommandPreprocessEvent extends PlayerEvent implements Cancell /** * Sets the command that the player will send. - * All commands begin with a special character; implementations do not consider the first character when executing the content. + * <p> + * All commands begin with a special character; implementations do not + * consider the first character when executing the content. * * @param command New message that the player will send * @throws IllegalArgumentException if command is null or empty @@ -110,7 +114,8 @@ public class PlayerCommandPreprocessEvent extends PlayerEvent implements Cancell /** * Gets the format to use to display this chat message * - * @deprecated This method is provided for backward compatibility with no guarantee to the use of the format. + * @deprecated This method is provided for backward compatibility with no + * guarantee to the use of the format. * @return String.Format compatible format string */ @Deprecated @@ -121,7 +126,8 @@ public class PlayerCommandPreprocessEvent extends PlayerEvent implements Cancell /** * Sets the format to use to display this chat message * - * @deprecated This method is provided for backward compatibility with no guarantee to the effect of modifying the format. + * @deprecated This method is provided for backward compatibility with no + * guarantee to the effect of modifying the format. * @param format String.Format compatible format string */ @Deprecated @@ -139,11 +145,16 @@ public class PlayerCommandPreprocessEvent extends PlayerEvent implements Cancell /** * Gets a set of recipients that this chat message will be displayed to. - * The set returned is not guaranteed to be mutable and may auto-populate on access. - * Any listener accessing the returned set should be aware that it may reduce performance for a lazy set implementation. - * Listeners should be aware that modifying the list may throw {@link UnsupportedOperationException} if the event caller provides an unmodifiable set. + * <p> + * The set returned is not guaranteed to be mutable and may auto-populate + * on access. Any listener accessing the returned set should be aware that + * it may reduce performance for a lazy set implementation. Listeners + * should be aware that modifying the list may throw {@link + * UnsupportedOperationException} if the event caller provides an + * unmodifiable set. * - * @deprecated This method is provided for backward compatibility with no guarantee to the effect of viewing or modifying the set. + * @deprecated This method is provided for backward compatibility with no + * guarantee to the effect of viewing or modifying the set. * @return All Players who will see this chat message */ @Deprecated diff --git a/src/main/java/org/bukkit/event/player/PlayerEditBookEvent.java b/src/main/java/org/bukkit/event/player/PlayerEditBookEvent.java index da411d99..ea7ecefe 100644 --- a/src/main/java/org/bukkit/event/player/PlayerEditBookEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerEditBookEvent.java @@ -8,8 +8,8 @@ import org.bukkit.event.HandlerList; import org.bukkit.inventory.meta.BookMeta; /** - * Called when a player edits or signs a book and quill item. If the event - * is cancelled, no changes are made to the BookMeta + * Called when a player edits or signs a book and quill item. If the event is + * cancelled, no changes are made to the BookMeta */ public class PlayerEditBookEvent extends PlayerEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); @@ -39,7 +39,7 @@ public class PlayerEditBookEvent extends PlayerEvent implements Cancellable { /** * Gets the book meta currently on the book. * <p> - * Note: this is a copy of the book meta. You cannot use this object to + * Note: this is a copy of the book meta. You cannot use this object to * change the existing book meta. * * @return the book meta currently on the book @@ -49,12 +49,11 @@ public class PlayerEditBookEvent extends PlayerEvent implements Cancellable { } /** - * Gets the book meta that the player is attempting to add to - * the book. + * Gets the book meta that the player is attempting to add to the book. * <p> * Note: this is a copy of the proposed new book meta. Use {@link - * #setNewBookMeta(BookMeta)} to change what will actually be - * added to the book. + * #setNewBookMeta(BookMeta)} to change what will actually be added to the + * book. * * @return the book meta that the player is attempting to add */ diff --git a/src/main/java/org/bukkit/event/player/PlayerEggThrowEvent.java b/src/main/java/org/bukkit/event/player/PlayerEggThrowEvent.java index 31ecbfa8..896347e6 100644 --- a/src/main/java/org/bukkit/event/player/PlayerEggThrowEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerEggThrowEvent.java @@ -51,8 +51,8 @@ public class PlayerEggThrowEvent extends PlayerEvent { /** * Sets whether the egg will hatch or not. * - * @param hatching true if you want the egg to hatch - * false if you want it not to + * @param hatching true if you want the egg to hatch, false if you want it + * not to */ public void setHatching(boolean hatching) { this.hatching = hatching; @@ -100,12 +100,13 @@ public class PlayerEggThrowEvent extends PlayerEvent { } /** - * Get the number of mob hatches from the egg. By default the number - * will be he number the server would've done - * <p> - * 7/8 chance of being 0 - * 31/256 ~= 1/8 chance to be 1 - * 1/256 chance to be 4 + * Get the number of mob hatches from the egg. By default the number will + * be the number the server would've done + * <ul> + * <li>7/8 chance of being 0 + * <li>31/256 ~= 1/8 chance to be 1 + * <li>1/256 chance to be 4 + * </ul> * * @return The number of mobs going to be hatched by the egg */ @@ -116,8 +117,8 @@ public class PlayerEggThrowEvent extends PlayerEvent { /** * Change the number of mobs coming out of the hatched egg * <p> - * The boolean hatching will override this number. - * Ie. If hatching = false, this number will not matter + * The boolean hatching will override this number. Ie. If hatching = + * false, this number will not matter * * @param numHatches The number of mobs coming out of the egg */ diff --git a/src/main/java/org/bukkit/event/player/PlayerFishEvent.java b/src/main/java/org/bukkit/event/player/PlayerFishEvent.java index dd8e2c0c..e92acdfc 100644 --- a/src/main/java/org/bukkit/event/player/PlayerFishEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerFishEvent.java @@ -19,7 +19,7 @@ public class PlayerFishEvent extends PlayerEvent implements Cancellable { /** * @deprecated replaced by {@link #PlayerFishEvent(Player, Entity, Fish, - * State)} to include the {@link Fish} hook entity. + * State)} to include the {@link Fish} hook entity. * @param player * @param entity * @param state @@ -39,7 +39,8 @@ public class PlayerFishEvent extends PlayerEvent implements Cancellable { /** * Gets the entity caught by the player * - * @return Entity caught by the player, null if fishing, bobber has gotten stuck in the ground or nothing has been caught + * @return Entity caught by the player, null if fishing, bobber has gotten + * stuck in the ground or nothing has been caught */ public Entity getCaught() { return entity; @@ -65,7 +66,8 @@ public class PlayerFishEvent extends PlayerEvent implements Cancellable { /** * Gets the amount of experience received when fishing. * <p> - * Note: This value has no default effect unless the event state is {@link State#CAUGHT_FISH}. + * Note: This value has no default effect unless the event state is {@link + * State#CAUGHT_FISH}. * * @return the amount of experience to drop */ @@ -76,7 +78,8 @@ public class PlayerFishEvent extends PlayerEvent implements Cancellable { /** * Sets the amount of experience received when fishing. * <p> - * Note: This value has no default effect unless the event state is {@link State#CAUGHT_FISH}. + * Note: This value has no default effect unless the event state is {@link + * State#CAUGHT_FISH}. * * @param amount the amount of experience to drop */ @@ -124,7 +127,8 @@ public class PlayerFishEvent extends PlayerEvent implements Cancellable { */ IN_GROUND, /** - * When a player fails to catch anything while fishing usually due to poor aiming or timing + * When a player fails to catch anything while fishing usually due to + * poor aiming or timing */ FAILED_ATTEMPT, } diff --git a/src/main/java/org/bukkit/event/player/PlayerInteractEvent.java b/src/main/java/org/bukkit/event/player/PlayerInteractEvent.java index a5dfc0bb..59567d99 100644 --- a/src/main/java/org/bukkit/event/player/PlayerInteractEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerInteractEvent.java @@ -42,8 +42,8 @@ public class PlayerInteractEvent extends PlayerEvent implements Cancellable { } /** - * Gets the cancellation state of this event. Set to true if you - * want to prevent buckets from placing water and so forth + * Gets the cancellation state of this event. Set to true if you want to + * prevent buckets from placing water and so forth * * @return boolean cancellation state */ @@ -52,8 +52,8 @@ public class PlayerInteractEvent extends PlayerEvent implements Cancellable { } /** - * Sets the cancellation state of this event. A canceled event will not - * be executed in the server, but will still pass to other plugins + * Sets the cancellation state of this event. A canceled event will not be + * executed in the server, but will still pass to other plugins * <p> * Canceling this event will prevent use of food (player won't lose the * food item), prevent bows/snowballs/eggs from firing, etc. (player won't @@ -76,8 +76,8 @@ public class PlayerInteractEvent extends PlayerEvent implements Cancellable { } /** - * Convenience method. Returns the material of the item represented by this - * event + * Convenience method. Returns the material of the item represented by + * this event * * @return Material the material of the item used */ @@ -108,8 +108,8 @@ public class PlayerInteractEvent extends PlayerEvent implements Cancellable { } /** - * Convenience method to inform the user whether this was a block placement - * event. + * Convenience method to inform the user whether this was a block + * placement event. * * @return boolean true if the item in hand was a block */ @@ -140,8 +140,9 @@ public class PlayerInteractEvent extends PlayerEvent implements Cancellable { } /** - * This controls the action to take with the block (if any) that was clicked on - * This event gets processed for all blocks, but most don't have a default action + * This controls the action to take with the block (if any) that was + * clicked on. This event gets processed for all blocks, but most don't + * have a default action * * @return the action to take with the interacted block */ @@ -157,9 +158,10 @@ public class PlayerInteractEvent extends PlayerEvent implements Cancellable { } /** - * This controls the action to take with the item the player is holding - * This includes both blocks and items (such as flint and steel or records) - * When this is set to default, it will be allowed if no action is taken on the interacted block + * This controls the action to take with the item the player is holding. + * This includes both blocks and items (such as flint and steel or + * records). When this is set to default, it will be allowed if no action + * is taken on the interacted block. * * @return the action to take with the item in hand */ diff --git a/src/main/java/org/bukkit/event/player/PlayerInventoryEvent.java b/src/main/java/org/bukkit/event/player/PlayerInventoryEvent.java index 8c67ee4b..2ec69d78 100644 --- a/src/main/java/org/bukkit/event/player/PlayerInventoryEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerInventoryEvent.java @@ -7,9 +7,12 @@ import org.bukkit.event.inventory.InventoryOpenEvent; import org.bukkit.inventory.Inventory; /** - * Represents a player related inventory event; note that this event never actually did anything - * @deprecated Use {@link InventoryClickEvent} or {@link InventoryOpenEvent} instead, or one of - * the other inventory events in {@link org.bukkit.event.inventory}. + * Represents a player related inventory event; note that this event never + * actually did anything + * + * @deprecated Use {@link InventoryClickEvent} or {@link InventoryOpenEvent} + * instead, or one of the other inventory events in {@link + * org.bukkit.event.inventory}. */ @Deprecated public class PlayerInventoryEvent extends PlayerEvent { diff --git a/src/main/java/org/bukkit/event/player/PlayerItemBreakEvent.java b/src/main/java/org/bukkit/event/player/PlayerItemBreakEvent.java index 6b338e26..176cd918 100644 --- a/src/main/java/org/bukkit/event/player/PlayerItemBreakEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerItemBreakEvent.java @@ -6,8 +6,9 @@ import org.bukkit.inventory.ItemStack; /** * Fired when a player's item breaks (such as a shovel or flint and steel). - * The item that's breaking will exist in the inventory with a stack size of 0. - * After the event, the item's durability will be reset to 0. + * <p> + * The item that's breaking will exist in the inventory with a stack size of + * 0. After the event, the item's durability will be reset to 0. */ public class PlayerItemBreakEvent extends PlayerEvent { private static final HandlerList handlers = new HandlerList(); diff --git a/src/main/java/org/bukkit/event/player/PlayerLoginEvent.java b/src/main/java/org/bukkit/event/player/PlayerLoginEvent.java index 60c08756..b74b7b89 100644 --- a/src/main/java/org/bukkit/event/player/PlayerLoginEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerLoginEvent.java @@ -32,11 +32,13 @@ public class PlayerLoginEvent extends PlayerEvent { } /** - * This constructor defaults message to an empty string, and result to ALLOWED + * This constructor defaults message to an empty string, and result to + * ALLOWED * * @param player The {@link Player} for this event * @param hostname The hostname that was used to connect to the server - * @param address The address the player used to connect, provided for timing issues + * @param address The address the player used to connect, provided for + * timing issues */ public PlayerLoginEvent(final Player player, final String hostname, final InetAddress address) { super(player); @@ -45,7 +47,8 @@ public class PlayerLoginEvent extends PlayerEvent { } /** - * @deprecated Address and hostname should be provided in other constructor + * @deprecated Address and hostname should be provided in other + * constructor */ @Deprecated public PlayerLoginEvent(final Player player, final Result result, final String message) { @@ -57,7 +60,8 @@ public class PlayerLoginEvent extends PlayerEvent { * * @param player The {@link Player} for this event * @param hostname The hostname that was used to connect to the server - * @param address The address the player used to connect, provided for timing issues + * @param address The address the player used to connect, provided for + * timing issues * @param result The result status for this event * @param message The message to be displayed if result denies login */ @@ -86,7 +90,8 @@ public class PlayerLoginEvent extends PlayerEvent { } /** - * Gets the current kick message that will be used if getResult() != Result.ALLOWED + * Gets the current kick message that will be used if getResult() != + * Result.ALLOWED * * @return Current kick message */ @@ -104,7 +109,8 @@ public class PlayerLoginEvent extends PlayerEvent { } /** - * Gets the hostname that the player used to connect to the server, or blank if unknown + * Gets the hostname that the player used to connect to the server, or + * blank if unknown * * @return The hostname */ @@ -132,12 +138,12 @@ public class PlayerLoginEvent extends PlayerEvent { } /** - * Gets the {@link InetAddress} for the Player associated - * with this event. This method is provided as a workaround for - * player.getAddress() returning null during PlayerLoginEvent. + * Gets the {@link InetAddress} for the Player associated with this event. + * This method is provided as a workaround for player.getAddress() + * returning null during PlayerLoginEvent. * - * @return The address for this player. For legacy compatibility, - * this may be null. + * @return The address for this player. For legacy compatibility, this may + * be null. */ public InetAddress getAddress() { return address; @@ -170,7 +176,8 @@ public class PlayerLoginEvent extends PlayerEvent { */ KICK_BANNED, /** - * The player is not allowed to log in, due to them not being on the white list + * The player is not allowed to log in, due to them not being on the + * white list */ KICK_WHITELIST, /** diff --git a/src/main/java/org/bukkit/event/player/PlayerPreLoginEvent.java b/src/main/java/org/bukkit/event/player/PlayerPreLoginEvent.java index bc622488..b86ba5da 100644 --- a/src/main/java/org/bukkit/event/player/PlayerPreLoginEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerPreLoginEvent.java @@ -8,7 +8,10 @@ import org.bukkit.event.HandlerList; /** * Stores details for players attempting to log in - * @deprecated This event causes synchronization from the login thread; {@link AsyncPlayerPreLoginEvent} is preferred to keep the secondary threads asynchronous. + * + * @deprecated This event causes synchronization from the login thread; {@link + * AsyncPlayerPreLoginEvent} is preferred to keep the secondary threads + * asynchronous. */ @Deprecated @Warning(reason="This event causes a login thread to synchronize with the main thread") @@ -45,7 +48,8 @@ public class PlayerPreLoginEvent extends Event { } /** - * Gets the current kick message that will be used if getResult() != Result.ALLOWED + * Gets the current kick message that will be used if getResult() != + * Result.ALLOWED * * @return Current kick message */ @@ -126,7 +130,8 @@ public class PlayerPreLoginEvent extends Event { */ KICK_BANNED, /** - * The player is not allowed to log in, due to them not being on the white list + * The player is not allowed to log in, due to them not being on the + * white list */ KICK_WHITELIST, /** diff --git a/src/main/java/org/bukkit/event/player/PlayerRegisterChannelEvent.java b/src/main/java/org/bukkit/event/player/PlayerRegisterChannelEvent.java index c0b47aa4..442ac7fb 100644 --- a/src/main/java/org/bukkit/event/player/PlayerRegisterChannelEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerRegisterChannelEvent.java @@ -1,13 +1,13 @@ -package org.bukkit.event.player;
-
-import org.bukkit.entity.Player;
-
-/**
- * This is called immediately after a player registers for a plugin channel.
- */
-public class PlayerRegisterChannelEvent extends PlayerChannelEvent {
-
- public PlayerRegisterChannelEvent(final Player player, final String channel) {
- super(player, channel);
- }
-}
+package org.bukkit.event.player; + +import org.bukkit.entity.Player; + +/** + * This is called immediately after a player registers for a plugin channel. + */ +public class PlayerRegisterChannelEvent extends PlayerChannelEvent { + + public PlayerRegisterChannelEvent(final Player player, final String channel) { + super(player, channel); + } +} diff --git a/src/main/java/org/bukkit/event/player/PlayerRespawnEvent.java b/src/main/java/org/bukkit/event/player/PlayerRespawnEvent.java index 48a07c29..35900dd1 100644 --- a/src/main/java/org/bukkit/event/player/PlayerRespawnEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerRespawnEvent.java @@ -5,6 +5,9 @@ import org.bukkit.Location; import org.bukkit.entity.Player; import org.bukkit.event.HandlerList; +/** + * Called when a player respawns. + */ public class PlayerRespawnEvent extends PlayerEvent { private static final HandlerList handlers = new HandlerList(); private Location respawnLocation; diff --git a/src/main/java/org/bukkit/event/player/PlayerTeleportEvent.java b/src/main/java/org/bukkit/event/player/PlayerTeleportEvent.java index 55b12fac..7e2e1288 100644 --- a/src/main/java/org/bukkit/event/player/PlayerTeleportEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerTeleportEvent.java @@ -32,11 +32,13 @@ public class PlayerTeleportEvent extends PlayerMoveEvent { public enum TeleportCause { /** - * Indicates the teleporation was caused by a player throwing an Ender Pearl + * Indicates the teleporation was caused by a player throwing an Ender + * Pearl */ ENDER_PEARL, /** - * Indicates the teleportation was caused by a player executing a command + * Indicates the teleportation was caused by a player executing a + * command */ COMMAND, /** @@ -44,15 +46,18 @@ public class PlayerTeleportEvent extends PlayerMoveEvent { */ PLUGIN, /** - * Indicates the teleportation was caused by a player entering a Nether portal + * Indicates the teleportation was caused by a player entering a + * Nether portal */ NETHER_PORTAL, /** - * Indicates the teleportation was caused by a player entering an End portal + * Indicates the teleportation was caused by a player entering an End + * portal */ END_PORTAL, /** - * Indicates the teleportation was caused by an event not covered by this enum + * Indicates the teleportation was caused by an event not covered by + * this enum */ UNKNOWN; } diff --git a/src/main/java/org/bukkit/event/player/PlayerUnregisterChannelEvent.java b/src/main/java/org/bukkit/event/player/PlayerUnregisterChannelEvent.java index e0a6f3d4..11c77e35 100644 --- a/src/main/java/org/bukkit/event/player/PlayerUnregisterChannelEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerUnregisterChannelEvent.java @@ -1,13 +1,13 @@ -package org.bukkit.event.player;
-
-import org.bukkit.entity.Player;
-
-/**
- * This is called immediately after a player unregisters for a plugin channel.
- */
-public class PlayerUnregisterChannelEvent extends PlayerChannelEvent {
-
- public PlayerUnregisterChannelEvent(final Player player, final String channel) {
- super(player, channel);
- }
-}
+package org.bukkit.event.player; + +import org.bukkit.entity.Player; + +/** + * This is called immediately after a player unregisters for a plugin channel. + */ +public class PlayerUnregisterChannelEvent extends PlayerChannelEvent { + + public PlayerUnregisterChannelEvent(final Player player, final String channel) { + super(player, channel); + } +} diff --git a/src/main/java/org/bukkit/event/player/PlayerVelocityEvent.java b/src/main/java/org/bukkit/event/player/PlayerVelocityEvent.java index 14cd0e95..69d2fce4 100644 --- a/src/main/java/org/bukkit/event/player/PlayerVelocityEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerVelocityEvent.java @@ -1,64 +1,55 @@ -package org.bukkit.event.player;
-
-import org.bukkit.entity.Player;
-import org.bukkit.event.Cancellable;
-import org.bukkit.event.HandlerList;
-import org.bukkit.util.Vector;
-
-public class PlayerVelocityEvent extends PlayerEvent implements Cancellable {
- private static final HandlerList handlers = new HandlerList();
- private boolean cancel = false;
- private Vector velocity;
-
- public PlayerVelocityEvent(final Player player, final Vector velocity) {
- super(player);
- this.velocity = velocity;
- }
-
- /**
- * Gets the cancellation state of this event. A cancelled event will not
- * be executed in the server, but will still pass to other plugins
- *
- * @return true if this event is cancelled
- */
- public boolean isCancelled() {
- return cancel;
- }
-
- /**
- * Sets the cancellation state of this event. A cancelled event will not
- * be executed in the server, but will still pass to other plugins
- *
- * @param cancel true if you wish to cancel this event
- */
- public void setCancelled(boolean cancel) {
- this.cancel = cancel;
- }
-
- /**
- * Gets the velocity vector that will be sent to the player
- *
- * @return Vector the player will get
- */
- public Vector getVelocity() {
- return velocity;
- }
-
- /**
- * Sets the velocity vector that will be sent to the player
- *
- * @param velocity The velocity vector that will be sent to the player
- */
- public void setVelocity(Vector velocity) {
- this.velocity = velocity;
- }
-
- @Override
- public HandlerList getHandlers() {
- return handlers;
- }
-
- public static HandlerList getHandlerList() {
- return handlers;
- }
-}
+package org.bukkit.event.player; + +import org.bukkit.entity.Player; +import org.bukkit.event.Cancellable; +import org.bukkit.event.HandlerList; +import org.bukkit.util.Vector; + +/** + * Called when the velocity of a player changes. + */ +public class PlayerVelocityEvent extends PlayerEvent implements Cancellable { + private static final HandlerList handlers = new HandlerList(); + private boolean cancel = false; + private Vector velocity; + + public PlayerVelocityEvent(final Player player, final Vector velocity) { + super(player); + this.velocity = velocity; + } + + public boolean isCancelled() { + return cancel; + } + + public void setCancelled(boolean cancel) { + this.cancel = cancel; + } + + /** + * Gets the velocity vector that will be sent to the player + * + * @return Vector the player will get + */ + public Vector getVelocity() { + return velocity; + } + + /** + * Sets the velocity vector that will be sent to the player + * + * @param velocity The velocity vector that will be sent to the player + */ + public void setVelocity(Vector velocity) { + this.velocity = velocity; + } + + @Override + public HandlerList getHandlers() { + return handlers; + } + + public static HandlerList getHandlerList() { + return handlers; + } +} diff --git a/src/main/java/org/bukkit/event/server/ServerCommandEvent.java b/src/main/java/org/bukkit/event/server/ServerCommandEvent.java index edf4e2a4..8a5972ae 100644 --- a/src/main/java/org/bukkit/event/server/ServerCommandEvent.java +++ b/src/main/java/org/bukkit/event/server/ServerCommandEvent.java @@ -48,7 +48,8 @@ public class ServerCommandEvent extends ServerEvent { } /** - * Gets the command that the user is attempting to execute from the console + * Gets the command that the user is attempting to execute from the + * console * * @return Command the user is attempting to execute */ diff --git a/src/main/java/org/bukkit/event/server/ServerListPingEvent.java b/src/main/java/org/bukkit/event/server/ServerListPingEvent.java index e138e3ad..5c368b6c 100644 --- a/src/main/java/org/bukkit/event/server/ServerListPingEvent.java +++ b/src/main/java/org/bukkit/event/server/ServerListPingEvent.java @@ -80,9 +80,9 @@ public class ServerListPingEvent extends ServerEvent { * Sets the server-icon sent to the client. * * @param icon the icon to send to the client - * @throws IllegalArgumentException if the {@link CachedServerIcon} is - * not created by the caller of this event; null may be accepted for - * some implementations + * @throws IllegalArgumentException if the {@link CachedServerIcon} is not + * created by the caller of this event; null may be accepted for some + * implementations * @throws UnsupportedOperationException if the caller of this event does * not support setting the server icon */ diff --git a/src/main/java/org/bukkit/event/server/ServiceEvent.java b/src/main/java/org/bukkit/event/server/ServiceEvent.java index 311e153b..69bf8723 100644 --- a/src/main/java/org/bukkit/event/server/ServiceEvent.java +++ b/src/main/java/org/bukkit/event/server/ServiceEvent.java @@ -3,7 +3,8 @@ package org.bukkit.event.server; import org.bukkit.plugin.RegisteredServiceProvider; /** - * An event relating to a registered service. This is called in a {@link org.bukkit.plugin.ServicesManager} + * An event relating to a registered service. This is called in a {@link + * org.bukkit.plugin.ServicesManager} */ public abstract class ServiceEvent extends ServerEvent { private final RegisteredServiceProvider<?> provider; diff --git a/src/main/java/org/bukkit/event/server/ServiceRegisterEvent.java b/src/main/java/org/bukkit/event/server/ServiceRegisterEvent.java index 628110aa..7dfadde1 100644 --- a/src/main/java/org/bukkit/event/server/ServiceRegisterEvent.java +++ b/src/main/java/org/bukkit/event/server/ServiceRegisterEvent.java @@ -4,9 +4,10 @@ import org.bukkit.event.HandlerList; import org.bukkit.plugin.RegisteredServiceProvider; /** - * This event is called when a service is registered.<br> - * <b>Warning:</b> The order in which register and unregister - * events are called should not be relied upon. + * This event is called when a service is registered. + * <p> + * Warning: The order in which register and unregister events are called + * should not be relied upon. */ public class ServiceRegisterEvent extends ServiceEvent { private static final HandlerList handlers = new HandlerList(); diff --git a/src/main/java/org/bukkit/event/server/ServiceUnregisterEvent.java b/src/main/java/org/bukkit/event/server/ServiceUnregisterEvent.java index e018f8e6..db61d236 100644 --- a/src/main/java/org/bukkit/event/server/ServiceUnregisterEvent.java +++ b/src/main/java/org/bukkit/event/server/ServiceUnregisterEvent.java @@ -4,9 +4,10 @@ import org.bukkit.event.HandlerList; import org.bukkit.plugin.RegisteredServiceProvider; /** - * This event is called when a service is unregistered.<br> - * <b>Warning:</b> The order in which register and unregister - * events are called should not be relied upon. + * This event is called when a service is unregistered. + * <p> + * Warning: The order in which register and unregister events are called + * should not be relied upon. */ public class ServiceUnregisterEvent extends ServiceEvent { private static final HandlerList handlers = new HandlerList(); diff --git a/src/main/java/org/bukkit/event/vehicle/VehicleDestroyEvent.java b/src/main/java/org/bukkit/event/vehicle/VehicleDestroyEvent.java index 7a481d3a..f1176fd2 100644 --- a/src/main/java/org/bukkit/event/vehicle/VehicleDestroyEvent.java +++ b/src/main/java/org/bukkit/event/vehicle/VehicleDestroyEvent.java @@ -6,9 +6,9 @@ import org.bukkit.event.Cancellable; import org.bukkit.event.HandlerList; /** - * Raised when a vehicle is destroyed, which could be caused by either a player - * or the environment. This is not raised if the boat is simply 'removed' - * due to other means. + * Raised when a vehicle is destroyed, which could be caused by either a + * player or the environment. This is not raised if the boat is simply + * 'removed' due to other means. */ public class VehicleDestroyEvent extends VehicleEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); diff --git a/src/main/java/org/bukkit/event/world/ChunkLoadEvent.java b/src/main/java/org/bukkit/event/world/ChunkLoadEvent.java index 906fa43d..a45b1cd4 100644 --- a/src/main/java/org/bukkit/event/world/ChunkLoadEvent.java +++ b/src/main/java/org/bukkit/event/world/ChunkLoadEvent.java @@ -17,6 +17,7 @@ public class ChunkLoadEvent extends ChunkEvent { /** * Gets if this chunk was newly created or not. + * <p> * Note that if this chunk is new, it will not be populated at this time. * * @return true if the chunk is new, otherwise false diff --git a/src/main/java/org/bukkit/event/world/ChunkPopulateEvent.java b/src/main/java/org/bukkit/event/world/ChunkPopulateEvent.java index 71106f37..705d9556 100644 --- a/src/main/java/org/bukkit/event/world/ChunkPopulateEvent.java +++ b/src/main/java/org/bukkit/event/world/ChunkPopulateEvent.java @@ -7,7 +7,8 @@ import org.bukkit.generator.BlockPopulator; /** * Thrown when a new chunk has finished being populated. * <p> - * If your intent is to populate the chunk using this event, please see {@link BlockPopulator} + * If your intent is to populate the chunk using this event, please see {@link + * BlockPopulator} */ public class ChunkPopulateEvent extends ChunkEvent { private static final HandlerList handlers = new HandlerList(); diff --git a/src/main/java/org/bukkit/event/world/PortalCreateEvent.java b/src/main/java/org/bukkit/event/world/PortalCreateEvent.java index 6f1183a7..d83d7a99 100644 --- a/src/main/java/org/bukkit/event/world/PortalCreateEvent.java +++ b/src/main/java/org/bukkit/event/world/PortalCreateEvent.java @@ -64,11 +64,13 @@ public class PortalCreateEvent extends WorldEvent implements Cancellable { */ public enum CreateReason { /** - * When a portal is created 'traditionally' due to a portal frame being set on fire. + * When a portal is created 'traditionally' due to a portal frame + * being set on fire. */ FIRE, /** - * When a portal is created as a destination for an existing portal when using the custom PortalTravelAgent + * When a portal is created as a destination for an existing portal + * when using the custom PortalTravelAgent */ OBC_DESTINATION } diff --git a/src/main/java/org/bukkit/event/world/SpawnChangeEvent.java b/src/main/java/org/bukkit/event/world/SpawnChangeEvent.java index d3cc1fcc..e99c3c01 100644 --- a/src/main/java/org/bukkit/event/world/SpawnChangeEvent.java +++ b/src/main/java/org/bukkit/event/world/SpawnChangeEvent.java @@ -5,8 +5,8 @@ import org.bukkit.Location; import org.bukkit.event.HandlerList; /** - * An event that is called when a world's spawn changes. The - * world's previous spawn location is included. + * An event that is called when a world's spawn changes. The world's previous + * spawn location is included. */ public class SpawnChangeEvent extends WorldEvent { private static final HandlerList handlers = new HandlerList(); diff --git a/src/main/java/org/bukkit/event/world/StructureGrowEvent.java b/src/main/java/org/bukkit/event/world/StructureGrowEvent.java index 15f4d419..d1c9822a 100644 --- a/src/main/java/org/bukkit/event/world/StructureGrowEvent.java +++ b/src/main/java/org/bukkit/event/world/StructureGrowEvent.java @@ -9,7 +9,8 @@ import org.bukkit.event.Cancellable; import org.bukkit.event.HandlerList; /** - * Event that is called when an organic structure attempts to grow (Sapling -> Tree), (Mushroom -> Huge Mushroom), naturally or using bonemeal. + * Event that is called when an organic structure attempts to grow (Sapling -> + * Tree), (Mushroom -> Huge Mushroom), naturally or using bonemeal. */ public class StructureGrowEvent extends WorldEvent implements Cancellable { private static final HandlerList handlers = new HandlerList(); @@ -39,7 +40,8 @@ public class StructureGrowEvent extends WorldEvent implements Cancellable { } /** - * Gets the species type (birch, normal, pine, red mushroom, brown mushroom) + * Gets the species type (birch, normal, pine, red mushroom, brown + * mushroom) * * @return Structure species */ @@ -59,7 +61,8 @@ public class StructureGrowEvent extends WorldEvent implements Cancellable { /** * Gets the player that created the structure. * - * @return Player that created the structure, null if was not created manually + * @return Player that created the structure, null if was not created + * manually */ public Player getPlayer() { return player; diff --git a/src/main/java/org/bukkit/event/world/WorldSaveEvent.java b/src/main/java/org/bukkit/event/world/WorldSaveEvent.java index ab4e5b59..d46b413c 100644 --- a/src/main/java/org/bukkit/event/world/WorldSaveEvent.java +++ b/src/main/java/org/bukkit/event/world/WorldSaveEvent.java @@ -3,6 +3,9 @@ package org.bukkit.event.world; import org.bukkit.World; import org.bukkit.event.HandlerList; +/** + * Called when a World is saved. + */ public class WorldSaveEvent extends WorldEvent { 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 eacc8294..6a70bdb8 100644 --- a/src/main/java/org/bukkit/generator/BlockPopulator.java +++ b/src/main/java/org/bukkit/generator/BlockPopulator.java @@ -6,18 +6,20 @@ import org.bukkit.World; /** * A block populator is responsible for generating a small area of blocks. - * For example, generating glowstone inside the nether or generating dungeons full of treasure + * <p> + * 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> - * The chunks on each side of the specified chunk must already exist; that is, - * there must be one north, east, south and west of the specified chunk. - * The "corner" chunks may not exist, in which scenario the populator should - * record any changes required for those chunks and perform the changes when - * they are ready. + * The chunks on each side of the specified chunk must already exist; that + * is, there must be one north, east, south and west of the specified + * chunk. The "corner" chunks may not exist, in which scenario the + * populator should record any changes required for those chunks and + * perform the changes when they are ready. * * @param world The world to generate in * @param random The random generator to use diff --git a/src/main/java/org/bukkit/generator/ChunkGenerator.java b/src/main/java/org/bukkit/generator/ChunkGenerator.java index 875f276b..8e08bdc9 100644 --- a/src/main/java/org/bukkit/generator/ChunkGenerator.java +++ b/src/main/java/org/bukkit/generator/ChunkGenerator.java @@ -10,17 +10,21 @@ import org.bukkit.block.Biome; import org.bukkit.block.Block; /** - * A chunk generator is responsible for the initial shaping of an entire chunk. - * For example, the nether chunk generator should shape netherrack and soulsand + * A chunk generator is responsible for the initial shaping of an entire + * chunk. 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. + * Interface to biome data for chunk to be generated: initialized with + * default values for world type and seed. * <p> - * Custom generator is free to access and tailor values during generateBlockSections() or generateExtBlockSections(). + * Custom generator is free to access and tailor values during + * generateBlockSections() or generateExtBlockSections(). */ public interface BiomeGrid { + /** * Get biome at x, z within chunk being generated * @@ -29,6 +33,7 @@ public abstract class ChunkGenerator { * @return Biome value */ Biome getBiome(int x, int z); + /** * Set biome at x, z within chunk being generated * @@ -43,7 +48,6 @@ public abstract class ChunkGenerator { * Shapes the chunk for the given coordinates. * <p> * This method should return a byte[32768] in the following format: - * * <pre> * for (int x = 0; x < 16; x++) { * for (int z = 0; z < 16; z++) { @@ -57,36 +61,43 @@ public abstract class ChunkGenerator { * Note that this method should <b>never</b> attempt to get the Chunk at * the passed coordinates, as doing so may cause an infinite loop * <p> - * Note this deprecated method will only be called when both generateExtBlockSections() - * and generateBlockSections() are unimplemented and return null. - + * Note this deprecated method will only be called when both + * generateExtBlockSections() and generateBlockSections() are + * unimplemented and return null. + * * @param world The world this chunk will be used for * @param random The random generator to use * @param x The X-coordinate of the chunk * @param z The Z-coordinate of the chunk - * @return byte[] containing the types for each block created by this generator + * @return byte[] containing the types for each block created by this + * generator */ public byte[] generate(World world, Random random, int x, int z) { throw new UnsupportedOperationException("Custom generator is missing required methods: generate(), generateBlockSections() and generateExtBlockSections()"); } /** - * Shapes the chunk for the given coordinates, with extended block IDs supported (0-4095). + * Shapes the chunk for the given coordinates, with extended block IDs + * supported (0-4095). * <p> - * As of 1.2, chunks are represented by a vertical array of chunk sections, each of which is 16 x 16 x 16 blocks. If a section - * is empty (all zero), the section does not need to be supplied, reducing memory usage. + * As of 1.2, chunks are represented by a vertical array of chunk + * sections, each of which is 16 x 16 x 16 blocks. If a section is empty + * (all zero), the section does not need to be supplied, reducing memory + * usage. * <p> * This method must return a short[][] array in the following format: * <pre> * short[][] result = new short[world-height / 16][]; * </pre> - * Each section (sectionID = (Y>>4)) that has blocks needs to be allocated space for the 4096 blocks in that section: + * Each section (sectionID = (Y>>4)) that has blocks needs to be allocated + * space for the 4096 blocks in that section: * <pre> * result[sectionID] = new short[4096]; * </pre> * while sections that are not populated can be left null. * <p> - * Setting a block at X, Y, Z within the chunk can be done with the following mapping function: + * Setting a block at X, Y, Z within the chunk can be done with the + * following mapping function: * <pre> * void setBlock(short[][] result, int x, int y, int z, short blkid) { * if (result[y >> 4] == null) { @@ -95,7 +106,8 @@ public abstract class ChunkGenerator { * result[y >> 4][((y & 0xF) << 8) | (z << 4) | x] = blkid; * } * </pre> - * while reading a block ID can be done with the following mapping function: + * while reading a block ID can be done with the following mapping + * function: * <pre> * short getBlock(short[][] result, int x, int y, int z) { * if (result[y >> 4] == null) { @@ -106,7 +118,8 @@ public abstract class ChunkGenerator { * </pre> * while sections that are not populated can be left null. * <p> - * Setting a block at X, Y, Z within the chunk can be done with the following mapping function: + * Setting a block at X, Y, Z within the chunk can be done with the + * following mapping function: * <pre> * void setBlock(short[][] result, int x, int y, int z, short blkid) { * if (result[y >> 4) == null) { @@ -115,7 +128,8 @@ public abstract class ChunkGenerator { * result[y >> 4][((y & 0xF) << 8) | (z << 4) | x] = blkid; * } * </pre> - * while reading a block ID can be done with the following mapping function: + * while reading a block ID can be done with the following mapping + * function: * <pre> * short getBlock(short[][] result, int x, int y, int z) { * if (result[y >> 4) == null) { @@ -128,16 +142,18 @@ public abstract class ChunkGenerator { * Note that this method should <b>never</b> attempt to get the Chunk at * the passed coordinates, as doing so may cause an infinite loop * <p> - * Note generators that do not return block IDs above 255 should not implement - * this method, or should have it return null (which will result in the - * generateBlockSections() method being called). + * Note generators that do not return block IDs above 255 should not + * implement this method, or should have it return null (which will result + * in the generateBlockSections() method being called). * * @param world The world this chunk will be used for * @param random The random generator to use * @param x The X-coordinate of the chunk * @param z The Z-coordinate of the chunk - * @param biomes Proposed biome values for chunk - can be updated by generator - * @return short[][] containing the types for each block created by this generator + * @param biomes Proposed biome values for chunk - can be updated by + * generator + * @return short[][] containing the types for each block created by this + * generator * @deprecated Magic value */ @Deprecated @@ -148,20 +164,24 @@ public abstract class ChunkGenerator { /** * Shapes the chunk for the given coordinates. * <p> - * As of 1.2, chunks are represented by a vertical array of chunk sections, each of which is 16 x 16 x 16 blocks. If a section - * is empty (all zero), the section does not need to be supplied, reducing memory usage. + * As of 1.2, chunks are represented by a vertical array of chunk + * sections, each of which is 16 x 16 x 16 blocks. If a section is empty + * (all zero), the section does not need to be supplied, reducing memory + * usage. * <p> * This method must return a byte[][] array in the following format: * <pre> * byte[][] result = new byte[world-height / 16][]; * </pre> - * Each section (sectionID = (Y>>4)) that has blocks needs to be allocated space for the 4096 blocks in that section: + * Each section (sectionID = (Y>>4)) that has blocks needs to be allocated + * space for the 4096 blocks in that section: * <pre> * result[sectionID] = new byte[4096]; * </pre> * while sections that are not populated can be left null. * <p> - * Setting a block at X, Y, Z within the chunk can be done with the following mapping function: + * Setting a block at X, Y, Z within the chunk can be done with the + * following mapping function: * <pre> * void setBlock(byte[][] result, int x, int y, int z, byte blkid) { * if (result[y >> 4) == null) { @@ -170,7 +190,8 @@ public abstract class ChunkGenerator { * result[y >> 4][((y & 0xF) << 8) | (z << 4) | x] = blkid; * } * </pre> - * while reading a block ID can be done with the following mapping function: + * while reading a block ID can be done with the following mapping + * function: * <pre> * byte getBlock(byte[][] result, int x, int y, int z) { * if (result[y >> 4) == null) { @@ -187,8 +208,10 @@ public abstract class ChunkGenerator { * @param random The random generator to use * @param x The X-coordinate of the chunk * @param z The Z-coordinate of the chunk - * @param biomes Proposed biome values for chunk - can be updated by generator - * @return short[][] containing the types for each block created by this generator + * @param biomes Proposed biome values for chunk - can be updated by + * generator + * @return short[][] containing the types for each block created by this + * generator * @deprecated Magic value */ @Deprecated @@ -219,7 +242,8 @@ public abstract class ChunkGenerator { } /** - * Gets a list of default {@link BlockPopulator}s to apply to a given world + * Gets a list of default {@link BlockPopulator}s to apply to a given + * world * * @param world World to apply to * @return List containing any amount of BlockPopulators diff --git a/src/main/java/org/bukkit/help/GenericCommandHelpTopic.java b/src/main/java/org/bukkit/help/GenericCommandHelpTopic.java index 639fd316..3e85e776 100644 --- a/src/main/java/org/bukkit/help/GenericCommandHelpTopic.java +++ b/src/main/java/org/bukkit/help/GenericCommandHelpTopic.java @@ -10,9 +10,10 @@ import org.bukkit.command.defaults.VanillaCommand; import org.bukkit.help.HelpTopic; /** - * Lacking an alternative, the help system will create instances of GenericCommandHelpTopic for each command in the - * server's CommandMap. You can use this class as a base class for custom help topics, or as an example for how to - * write your own. + * Lacking an alternative, the help system will create instances of + * GenericCommandHelpTopic for each command in the server's CommandMap. You + * can use this class as a base class for custom help topics, or as an example + * for how to write your own. */ public class GenericCommandHelpTopic extends HelpTopic { diff --git a/src/main/java/org/bukkit/help/HelpMap.java b/src/main/java/org/bukkit/help/HelpMap.java index a293633f..9c1b51be 100644 --- a/src/main/java/org/bukkit/help/HelpMap.java +++ b/src/main/java/org/bukkit/help/HelpMap.java @@ -4,20 +4,25 @@ import java.util.Collection; import java.util.List; /** - * The HelpMap tracks all help topics registered in a Bukkit server. When the server starts up or is reloaded, - * help is processed and topics are added in the following order: - * <p/> - * 1. General topics are loaded from the help.yml - * 2. Plugins load and optionally call {@code addTopic()} - * 3. Registered plugin commands are processed by {@link HelpTopicFactory} objects to create topics - * 4. Topic contents are amended as directed in help.yml + * The HelpMap tracks all help topics registered in a Bukkit server. When the + * server starts up or is reloaded, help is processed and topics are added in + * the following order: + * <p> + * <ol> + * <li>General topics are loaded from the help.yml + * <li>Plugins load and optionally call {@code addTopic()} + * <li>Registered plugin commands are processed by {@link HelpTopicFactory} + * objects to create topics + * <li>Topic contents are amended as directed in help.yml + * </ol> */ public interface HelpMap { /** * Returns a help topic for a given topic name. * * @param topicName The help topic name to look up. - * @return A {@link HelpTopic} object matching the topic name or null if none can be found. + * @return A {@link HelpTopic} object matching the topic name or null if + * none can be found. */ public HelpTopic getHelpTopic(String topicName); @@ -36,28 +41,36 @@ public interface HelpMap { public void addTopic(HelpTopic topic); /** - * Clears out the contents of the help index. Normally called during server reload. + * Clears out the contents of the help index. Normally called during + * server reload. */ public void clear(); /** - * Associates a {@link HelpTopicFactory} object with given command base class. Plugins typically - * call this method during {@code onLoad()}. Once registered, the custom HelpTopicFactory will - * be used to create a custom {@link HelpTopic} for all commands deriving from the {@code commandClass} - * base class, or all commands deriving from {@link org.bukkit.command.PluginCommand} who's executor - * derives from {@code commandClass} base class. + * Associates a {@link HelpTopicFactory} object with given command base + * class. Plugins typically call this method during {@code onLoad()}. Once + * registered, the custom HelpTopicFactory will be used to create a custom + * {@link HelpTopic} for all commands deriving from the {@code + * commandClass} base class, or all commands deriving from {@link + * org.bukkit.command.PluginCommand} who's executor derives from {@code + * commandClass} base class. * - * @param commandClass The class for which the custom HelpTopicFactory applies. Must derive from - * either {@link org.bukkit.command.Command} or {@link org.bukkit.command.CommandExecutor}. - * @param factory The {@link HelpTopicFactory} implementation to associate with the {@code commandClass}. - * @throws IllegalArgumentException Thrown if {@code commandClass} does not derive from a legal base class. + * @param commandClass The class for which the custom HelpTopicFactory + * applies. Must derive from either {@link org.bukkit.command.Command} + * or {@link org.bukkit.command.CommandExecutor}. + * @param factory The {@link HelpTopicFactory} implementation to associate + * with the {@code commandClass}. + * @throws IllegalArgumentException Thrown if {@code commandClass} does + * not derive from a legal base class. */ public void registerHelpTopicFactory(Class<?> commandClass, HelpTopicFactory<?> factory); /** - * Gets the list of plugins the server administrator has chosen to exclude from the help index. Plugin authors - * who choose to directly extend {@link org.bukkit.command.Command} instead of {@link org.bukkit.command.PluginCommand} - * will need to check this collection in their {@link HelpTopicFactory} implementations to ensure they meet the + * Gets the list of plugins the server administrator has chosen to exclude + * from the help index. Plugin authors who choose to directly extend + * {@link org.bukkit.command.Command} instead of {@link + * org.bukkit.command.PluginCommand} will need to check this collection in + * their {@link HelpTopicFactory} implementations to ensure they meet the * server administrator's expectations. * * @return A list of plugins that should be excluded from the help index. diff --git a/src/main/java/org/bukkit/help/HelpTopic.java b/src/main/java/org/bukkit/help/HelpTopic.java index 21984411..a2ba5f56 100644 --- a/src/main/java/org/bukkit/help/HelpTopic.java +++ b/src/main/java/org/bukkit/help/HelpTopic.java @@ -4,14 +4,16 @@ import org.bukkit.command.CommandSender; import org.bukkit.entity.Player; /** - * HelpTopic implementations are displayed to the user when the user uses the /help command. + * HelpTopic implementations are displayed to the user when the user uses the + * /help command. * <p> - * Custom implementations of this class can work at two levels. A simple implementation only - * needs to set the value of {@code name}, {@code shortText}, and {@code fullText} int the - * constructor. This base class will take care of the rest. + * Custom implementations of this class can work at two levels. A simple + * implementation only needs to set the value of {@code name}, {@code + * shortText}, and {@code fullText} in the constructor. This base class will + * take care of the rest. * <p> - * Complex implementations can be created by overriding the behavior of all the methods in - * this class. + * Complex implementations can be created by overriding the behavior of all + * the methods in this class. */ public abstract class HelpTopic { protected String name; @@ -20,8 +22,10 @@ public abstract class HelpTopic { protected String amendedPermission; /** - * Determines if a {@link Player} is allowed to see this help topic. HelpTopic implementations should take - * server administrator wishes into account as set by the {@link HelpTopic#amendCanSee(String)} function. + * Determines if a {@link Player} is allowed to see this help topic. + * <p> + * HelpTopic implementations should take server administrator wishes into + * account as set by the {@link HelpTopic#amendCanSee(String)} function. * * @param player The Player in question. * @return True of the Player can see this help topic, false otherwise. @@ -29,11 +33,15 @@ public abstract class HelpTopic { public abstract boolean canSee(CommandSender player); /** - * Allows the server administrator to override the permission required to see a help topic. HelpTopic - * implementations should take this into account when determining topic visibility on the - * {@link HelpTopic#canSee(org.bukkit.command.CommandSender)} function. + * Allows the server administrator to override the permission required to + * see a help topic. + * <p> + * HelpTopic implementations should take this into account when + * determining topic visibility on the {@link + * HelpTopic#canSee(org.bukkit.command.CommandSender)} function. * - * @param amendedPermission The permission node the server administrator wishes to apply to this topic. + * @param amendedPermission The permission node the server administrator + * wishes to apply to this topic. */ public void amendCanSee(String amendedPermission) { this.amendedPermission = amendedPermission; @@ -58,11 +66,14 @@ public abstract class HelpTopic { } /** - * Returns the full description of this help topic that is displayed when the user requests this topic's details. + * Returns the full description of this help topic that is displayed when + * the user requests this topic's details. + * <p> * The result will be paginated to properly fit the user's client. * - * @param forWho The player or console requesting the full text. Useful for further security trimming - * the command's full text based on sub-permissions in custom implementations. + * @param forWho The player or console requesting the full text. Useful + * for further security trimming the command's full text based on + * sub-permissions in custom implementations. * * @return A full topic description. */ @@ -71,13 +82,18 @@ public abstract class HelpTopic { } /** - * Allows the server admin (or another plugin) to add or replace the contents of a help topic. A null in - * either parameter will leave that part of the topic unchanged. In either amending parameter, the string - * {@literal <text>} is replaced with the existing contents in the help topic. Use this to append or prepend - * additional content into an automatically generated help topic. + * Allows the server admin (or another plugin) to add or replace the + * contents of a help topic. + * <p> + * A null in either parameter will leave that part of the topic unchanged. + * In either amending parameter, the string {@literal <text>} is replaced + * with the existing contents in the help topic. Use this to append or + * prepend additional content into an automatically generated help topic. * - * @param amendedShortText The new topic short text to use, or null to leave alone. - * @param amendedFullText The new topic full text to use, or null to leave alone. + * @param amendedShortText The new topic short text to use, or null to + * leave alone. + * @param amendedFullText The new topic full text to use, or null to leave + * alone. */ public void amendTopic(String amendedShortText, String amendedFullText) { shortText = applyAmendment(shortText, amendedShortText); @@ -85,14 +101,15 @@ public abstract class HelpTopic { } /** - * Developers implementing their own custom HelpTopic implementations can use this utility method to ensure - * their implementations comply with the expected behavior of the {@link HelpTopic#amendTopic(String, String)} + * Developers implementing their own custom HelpTopic implementations can + * use this utility method to ensure their implementations comply with the + * expected behavior of the {@link HelpTopic#amendTopic(String, String)} * method. * * @param baseText The existing text of the help topic. * @param amendment The amending text from the amendTopic() method. - * @return The application of the amending text to the existing text, according to the expected rules of - * amendTopic(). + * @return The application of the amending text to the existing text, + * according to the expected rules of amendTopic(). */ protected String applyAmendment(String baseText, String amendment) { if (amendment == null) { diff --git a/src/main/java/org/bukkit/help/HelpTopicComparator.java b/src/main/java/org/bukkit/help/HelpTopicComparator.java index 5ab094c0..3e43eb36 100644 --- a/src/main/java/org/bukkit/help/HelpTopicComparator.java +++ b/src/main/java/org/bukkit/help/HelpTopicComparator.java @@ -5,8 +5,10 @@ import org.bukkit.help.HelpTopic; import java.util.Comparator; /** - * Used to impose a custom total ordering on help topics. All topics are listed in alphabetic order, but topics - * that start with a slash come after topics that don't. + * Used to impose a custom total ordering on help topics. + * <p> + * All topics are listed in alphabetic order, but topics that start with a + * slash come after topics that don't. */ public class HelpTopicComparator implements Comparator<HelpTopic> { diff --git a/src/main/java/org/bukkit/help/HelpTopicFactory.java b/src/main/java/org/bukkit/help/HelpTopicFactory.java index 4f5c7866..87d36977 100644 --- a/src/main/java/org/bukkit/help/HelpTopicFactory.java +++ b/src/main/java/org/bukkit/help/HelpTopicFactory.java @@ -3,32 +3,40 @@ package org.bukkit.help; import org.bukkit.command.Command; /** - * A HelpTopicFactory is used to create custom {@link HelpTopic} objects from commands that inherit from a - * common base class or have executors that inherit from a common base class. You can use a custom HelpTopic to change - * the way all the commands in your plugin display in the help. If your plugin implements a complex permissions system, - * a custom help topic may also be appropriate. + * A HelpTopicFactory is used to create custom {@link HelpTopic} objects from + * commands that inherit from a common base class or have executors that + * inherit from a common base class. You can use a custom HelpTopic to change + * the way all the commands in your plugin display in the help. If your plugin + * implements a complex permissions system, a custom help topic may also be + * appropriate. * <p> - * To automatically bind your plugin's commands to your custom HelpTopic implementation, first make sure all your - * commands or executors derive from a custom base class (it doesn't have to do anything). Next implement a custom - * HelpTopicFactory that accepts your custom command base class and instantiates an instance of your custom HelpTopic - * from it. Finally, register your HelpTopicFactory against your command base class using the {@link HelpMap#registerHelpTopicFactory(Class, HelpTopicFactory)} - * method. + * To automatically bind your plugin's commands to your custom HelpTopic + * implementation, first make sure all your commands or executors derive from + * a custom base class (it doesn't have to do anything). Next implement a + * custom HelpTopicFactory that accepts your custom command base class and + * instantiates an instance of your custom HelpTopic from it. Finally, + * register your HelpTopicFactory against your command base class using the + * {@link HelpMap#registerHelpTopicFactory(Class, HelpTopicFactory)} method. * <p> - * As the help system iterates over all registered commands to make help topics, it first checks to see if there is a - * HelpTopicFactory registered for the command's base class. If so, the factory is used to make a help topic rather - * than a generic help topic. If no factory is found for the command's base class and the command derives from - * {@link org.bukkit.command.PluginCommand}, then the type of the command's executor is inspected looking for a registered - * HelpTopicFactory. Finally, if no factory is found, a generic help topic is created for the command. + * As the help system iterates over all registered commands to make help + * topics, it first checks to see if there is a HelpTopicFactory registered + * for the command's base class. If so, the factory is used to make a help + * topic rather than a generic help topic. If no factory is found for the + * command's base class and the command derives from {@link + * org.bukkit.command.PluginCommand}, then the type of the command's executor + * is inspected looking for a registered HelpTopicFactory. Finally, if no + * factory is found, a generic help topic is created for the command. * * @param <TCommand> The base class for your custom commands. */ public interface HelpTopicFactory<TCommand extends Command> { /** - * This method accepts a command deriving from a custom command base class and constructs a custom HelpTopic - * for it. + * This method accepts a command deriving from a custom command base class + * and constructs a custom HelpTopic for it. * * @param command The custom command to build a help topic for. - * @return A new custom help topic or {@code null} to intentionally NOT create a topic. + * @return A new custom help topic or {@code null} to intentionally NOT + * create a topic. */ public HelpTopic createTopic(TCommand command); } diff --git a/src/main/java/org/bukkit/help/IndexHelpTopic.java b/src/main/java/org/bukkit/help/IndexHelpTopic.java index 61db6c8d..c474031b 100644 --- a/src/main/java/org/bukkit/help/IndexHelpTopic.java +++ b/src/main/java/org/bukkit/help/IndexHelpTopic.java @@ -9,11 +9,12 @@ import org.bukkit.util.ChatPaginator; import java.util.Collection; /** - * This help topic generates a list of other help topics. This class is useful for adding your own - * index help topics. To enforce a particular order, use a sorted collection. - * <p/> - * If a preamble is provided to the constructor, that text will be displayed before the first item - * in the index. + * This help topic generates a list of other help topics. This class is useful + * for adding your own index help topics. To enforce a particular order, use a + * sorted collection. + * <p> + * If a preamble is provided to the constructor, that text will be displayed + * before the first item in the index. */ public class IndexHelpTopic extends HelpTopic { @@ -81,7 +82,8 @@ public class IndexHelpTopic extends HelpTopic { } /** - * Builds the topic preamble. Override this method to change how the index preamble looks. + * Builds the topic preamble. Override this method to change how the index + * preamble looks. * * @param sender The command sender requesting the preamble. * @return The topic preamble. @@ -91,7 +93,8 @@ public class IndexHelpTopic extends HelpTopic { } /** - * Builds individual lines in the index topic. Override this method to change how index lines are rendered. + * Builds individual lines in the index topic. Override this method to + * change how index lines are rendered. * * @param sender The command sender requesting the index line. * @param topic The topic to render into an index line. diff --git a/src/main/java/org/bukkit/inventory/AnvilInventory.java b/src/main/java/org/bukkit/inventory/AnvilInventory.java index 52c89647..70fae71b 100644 --- a/src/main/java/org/bukkit/inventory/AnvilInventory.java +++ b/src/main/java/org/bukkit/inventory/AnvilInventory.java @@ -1,4 +1,7 @@ package org.bukkit.inventory; +/** + * Interface to the inventory of an Anvil. + */ public interface AnvilInventory extends Inventory { } diff --git a/src/main/java/org/bukkit/inventory/BeaconInventory.java b/src/main/java/org/bukkit/inventory/BeaconInventory.java index d791f604..2f8769ed 100644 --- a/src/main/java/org/bukkit/inventory/BeaconInventory.java +++ b/src/main/java/org/bukkit/inventory/BeaconInventory.java @@ -1,5 +1,8 @@ package org.bukkit.inventory; +/** + * Interface to the inventory of a Beacon. + */ public interface BeaconInventory extends Inventory { /** @@ -8,6 +11,7 @@ public interface BeaconInventory extends Inventory { * @param item The new item */ void setItem(ItemStack item); + /** * Get 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 91cd276b..9cc31c97 100644 --- a/src/main/java/org/bukkit/inventory/BrewerInventory.java +++ b/src/main/java/org/bukkit/inventory/BrewerInventory.java @@ -2,6 +2,9 @@ package org.bukkit.inventory; import org.bukkit.block.BrewingStand; +/** + * Interface to the inventory of a Brewing Stand. + */ public interface BrewerInventory extends Inventory { /** @@ -10,6 +13,7 @@ public interface BrewerInventory extends Inventory { * @return The ingredient. */ ItemStack getIngredient(); + /** * Set 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 e3b31b5e..f71533c7 100644 --- a/src/main/java/org/bukkit/inventory/CraftingInventory.java +++ b/src/main/java/org/bukkit/inventory/CraftingInventory.java @@ -11,29 +11,35 @@ public interface CraftingInventory extends Inventory { * @return The result item. */ ItemStack getResult(); + /** * Get the contents of the crafting matrix. * * @return The contents. */ ItemStack[] getMatrix(); + /** * Set the item in the result slot of the crafting inventory. * * @param newResult The new result item. */ void setResult(ItemStack newResult); + /** * Replace the contents of the crafting matrix * * @param contents The new contents. - * @throws IllegalArgumentException if the length of contents is greater than the size of the crafting matrix. + * @throws IllegalArgumentException if the length of contents is greater + * than the size of the crafting matrix. */ void setMatrix(ItemStack[] contents); + /** * Get the current recipe formed on the crafting inventory, if any. * - * @return The recipe, or null if the current contents don't match any recipe. + * @return The recipe, or null if the current contents don't match any + * recipe. */ Recipe getRecipe(); }
\ No newline at end of file diff --git a/src/main/java/org/bukkit/inventory/DoubleChestInventory.java b/src/main/java/org/bukkit/inventory/DoubleChestInventory.java index 0e419ed2..c03ad535 100644 --- a/src/main/java/org/bukkit/inventory/DoubleChestInventory.java +++ b/src/main/java/org/bukkit/inventory/DoubleChestInventory.java @@ -2,6 +2,9 @@ package org.bukkit.inventory; import org.bukkit.block.DoubleChest; +/** + * Interface to the inventory of a Double Chest. + */ public interface DoubleChestInventory extends Inventory { /** diff --git a/src/main/java/org/bukkit/inventory/EnchantingInventory.java b/src/main/java/org/bukkit/inventory/EnchantingInventory.java index 9be1ee7f..74a863e1 100644 --- a/src/main/java/org/bukkit/inventory/EnchantingInventory.java +++ b/src/main/java/org/bukkit/inventory/EnchantingInventory.java @@ -1,5 +1,8 @@ package org.bukkit.inventory; +/** + * Interface to the inventory of an Enchantment Table. + */ public interface EnchantingInventory extends Inventory { /** @@ -8,6 +11,7 @@ public interface EnchantingInventory extends Inventory { * @param item The new item */ void setItem(ItemStack item); + /** * Get 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 de682a66..9e712359 100644 --- a/src/main/java/org/bukkit/inventory/EntityEquipment.java +++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java @@ -97,20 +97,26 @@ public interface EntityEquipment { void clear(); /** - * Gets the chance of the currently held item being dropped upon this creature's death + * Gets the chance of the currently held item being dropped upon this + * creature's death * <p> - * <li />A drop chance of 0F will never drop - * <li />A drop chance of 1F will always drop + * <ul> + * <li>A drop chance of 0F will never drop + * <li>A drop chance of 1F will always drop + * </ul> * * @return chance of the currently held item being dropped (1 for players) */ float getItemInHandDropChance(); /** - * Sets the chance of the item this creature is currently holding being dropped upon this creature's death + * Sets the chance of the item this creature is currently holding being + * dropped upon this creature's death * <p> - * <li />A drop chance of 0F will never drop - * <li />A drop chance of 1F will always drop + * <ul> + * <li>A drop chance of 0F will never drop + * <li>A drop chance of 1F will always drop + * </ul> * * @param chance the chance of the currently held item being dropped * @throws UnsupportedOperationException when called on players @@ -120,8 +126,10 @@ public interface EntityEquipment { /** * Gets the chance of the helmet being dropped upon this creature's death * <p> - * <li />A drop chance of 0F will never drop - * <li />A drop chance of 1F will always drop + * <ul> + * <li>A drop chance of 0F will never drop + * <li>A drop chance of 1F will always drop + * </ul> * * @return the chance of the helmet being dropped (1 for players) */ @@ -130,8 +138,10 @@ public interface EntityEquipment { /** * Sets the chance of the helmet being dropped upon this creature's death * <p> - * <li />A drop chance of 0F will never drop - * <li />A drop chance of 1F will always drop + * <ul> + * <li>A drop chance of 0F will never drop + * <li>A drop chance of 1F will always drop + * </ul> * * @param chance of the helmet being dropped * @throws UnsupportedOperationException when called on players @@ -139,20 +149,26 @@ public interface EntityEquipment { void setHelmetDropChance(float chance); /** - * Gets the chance of the chest plate being dropped upon this creature's death + * Gets the chance of the chest plate being dropped upon this creature's + * death * <p> - * <li />A drop chance of 0F will never drop - * <li />A drop chance of 1F will always drop + * <ul> + * <li>A drop chance of 0F will never drop + * <li>A drop chance of 1F will always drop + * </ul> * * @return the chance of the chest plate being dropped (1 for players) */ float getChestplateDropChance(); /** - * Sets the chance of the chest plate being dropped upon this creature's death + * Sets the chance of the chest plate being dropped upon this creature's + * death * <p> - * <li />A drop chance of 0F will never drop - * <li />A drop chance of 1F will always drop + * <ul> + * <li>A drop chance of 0F will never drop + * <li>A drop chance of 1F will always drop + * </ul> * * @param chance of the chest plate being dropped * @throws UnsupportedOperationException when called on players @@ -160,20 +176,26 @@ public interface EntityEquipment { void setChestplateDropChance(float chance); /** - * Gets the chance of the leggings being dropped upon this creature's death + * Gets the chance of the leggings being dropped upon this creature's + * death * <p> - * <li />A drop chance of 0F will never drop - * <li />A drop chance of 1F will always drop + * <ul> + * <li>A drop chance of 0F will never drop + * <li>A drop chance of 1F will always drop + * </ul> * * @return the chance of the leggings being dropped (1 for players) */ float getLeggingsDropChance(); /** - * Sets the chance of the leggings being dropped upon this creature's death + * Sets the chance of the leggings being dropped upon this creature's + * death * <p> - * <li />A drop chance of 0F will never drop - * <li />A drop chance of 1F will always drop + * <ul> + * <li>A drop chance of 0F will never drop + * <li>A drop chance of 1F will always drop + * </ul> * * @param chance chance of the leggings being dropped * @throws UnsupportedOperationException when called on players @@ -183,8 +205,10 @@ public interface EntityEquipment { /** * Gets the chance of the boots being dropped upon this creature's death * <p> - * <li />A drop chance of 0F will never drop - * <li />A drop chance of 1F will always drop + * <ul> + * <li>A drop chance of 0F will never drop + * <li>A drop chance of 1F will always drop + * </ul> * * @return the chance of the boots being dropped (1 for players) */ @@ -193,8 +217,10 @@ public interface EntityEquipment { /** * Sets the chance of the boots being dropped upon this creature's death * <p> - * <li />A drop chance of 0F will never drop - * <li />A drop chance of 1F will always drop + * <ul> + * <li>A drop chance of 0F will never drop + * <li>A drop chance of 1F will always drop + * </ul> * * @param chance of the boots being dropped * @throws UnsupportedOperationException when called on players diff --git a/src/main/java/org/bukkit/inventory/FurnaceInventory.java b/src/main/java/org/bukkit/inventory/FurnaceInventory.java index 5920083a..93b41d36 100644 --- a/src/main/java/org/bukkit/inventory/FurnaceInventory.java +++ b/src/main/java/org/bukkit/inventory/FurnaceInventory.java @@ -2,6 +2,9 @@ package org.bukkit.inventory; import org.bukkit.block.Furnace; +/** + * Interface to the inventory of a Furnace. + */ public interface FurnaceInventory extends Inventory { /** diff --git a/src/main/java/org/bukkit/inventory/FurnaceRecipe.java b/src/main/java/org/bukkit/inventory/FurnaceRecipe.java index ad9cc598..80753238 100644 --- a/src/main/java/org/bukkit/inventory/FurnaceRecipe.java +++ b/src/main/java/org/bukkit/inventory/FurnaceRecipe.java @@ -35,7 +35,8 @@ public class FurnaceRecipe implements Recipe { * * @param result The item you want the recipe to create. * @param source The input material. - * @param data The data value. (Note: This is currently ignored by the CraftBukkit server.) + * @param data The data value. (Note: This is currently ignored by the + * CraftBukkit server.) * @deprecated Magic value */ @Deprecated @@ -68,7 +69,8 @@ public class FurnaceRecipe implements Recipe { * Sets the input of this furnace recipe. * * @param input The input material. - * @param data The data value. (Note: This is currently ignored by the CraftBukkit server.) + * @param data The data value. (Note: This is currently ignored by the + * CraftBukkit server.) * @return The changed recipe, so you can chain calls. * @deprecated Magic value */ diff --git a/src/main/java/org/bukkit/inventory/HorseInventory.java b/src/main/java/org/bukkit/inventory/HorseInventory.java index f38a0989..a71efb83 100644 --- a/src/main/java/org/bukkit/inventory/HorseInventory.java +++ b/src/main/java/org/bukkit/inventory/HorseInventory.java @@ -1,5 +1,8 @@ package org.bukkit.inventory; +/** + * An interface to the inventory of a Horse. + */ public interface HorseInventory extends Inventory { /** diff --git a/src/main/java/org/bukkit/inventory/Inventory.java b/src/main/java/org/bukkit/inventory/Inventory.java index 436e7e49..da5d83e0 100644 --- a/src/main/java/org/bukkit/inventory/Inventory.java +++ b/src/main/java/org/bukkit/inventory/Inventory.java @@ -9,7 +9,8 @@ import org.bukkit.entity.HumanEntity; import org.bukkit.event.inventory.InventoryType; /** - * Interface to the various inventories. Behavior relating to {@link Material#AIR} is unspecified. + * Interface to the various inventories. Behavior relating to {@link + * Material#AIR} is unspecified. */ public interface Inventory extends Iterable<ItemStack> { @@ -28,15 +29,17 @@ public interface Inventory extends Iterable<ItemStack> { public int getMaxStackSize(); /** - * This method allows you to change the maximum stack size for an inventory. - * <p><b>Caveats:</b> + * This method allows you to change the maximum stack size for an + * inventory. + * <p> + * <b>Caveats:</b> * <ul> * <li>Not all inventories respect this value. * <li>Stacks larger than 127 may be clipped when the world is saved. - * <li>This value is not guaranteed to be preserved; be sure to set it before every time - * you want to set a slot over the max stack size. - * <li>Stacks larger than the default max size for this type of inventory may not display - * correctly in the client. + * <li>This value is not guaranteed to be preserved; be sure to set it + * before every time you want to set a slot over the max stack size. + * <li>Stacks larger than the default max size for this type of inventory + * may not display correctly in the client. * </ul> * * @param size The new maximum stack size for items in this inventory. @@ -67,13 +70,13 @@ public interface Inventory extends Iterable<ItemStack> { public void setItem(int index, ItemStack item); /** - * Stores the given ItemStacks in the inventory. - * This will try to fill existing stacks and empty slots as well as it can. + * Stores the given ItemStacks in the inventory. This will try to fill + * existing stacks and empty slots as well as it can. * <p> - * The returned HashMap contains what it couldn't store, where the key is the - * index of the parameter, and the value is the ItemStack at that index - * of the varargs parameter. If all items are stored, it will return an - * empty HashMap. + * The returned HashMap contains what it couldn't store, where the key is + * the index of the parameter, and the value is the ItemStack at that + * index of the varargs parameter. If all items are stored, it will return + * an empty HashMap. * <p> * If you pass in ItemStacks which exceed the maximum stack size for the * Material, first they will be added to partial stacks where @@ -91,13 +94,13 @@ public interface Inventory extends Iterable<ItemStack> { /** * Removes the given ItemStacks from the inventory. * <p> - * It will try to remove 'as much as possible' from the types and amounts you - * give as arguments. + * It will try to remove 'as much as possible' from the types and amounts + * you give as arguments. * <p> - * The returned HashMap contains what it couldn't remove, where the key is the - * index of the parameter, and the value is the ItemStack at that index of the - * varargs parameter. If all the given ItemStacks are removed, it will return - * an empty HashMap. + * The returned HashMap contains what it couldn't remove, where the key is + * the index of the parameter, and the value is the ItemStack at that + * index of the varargs parameter. If all the given ItemStacks are + * removed, it will return an empty HashMap. * * @param items The ItemStacks to remove * @return A HashMap containing items that couldn't be removed. @@ -116,13 +119,16 @@ public interface Inventory extends Iterable<ItemStack> { * Completely replaces the inventory's contents. Removes all existing * contents and replaces it with the ItemStacks given in the array. * - * @param items A complete replacement for the contents; the length must be less than or equal to {@link #getSize()}. - * @throws IllegalArgumentException If the array has more items than the inventory. + * @param items A complete replacement for the contents; the length must + * be less than or equal to {@link #getSize()}. + * @throws IllegalArgumentException If the array has more items than the + * inventory. */ public void setContents(ItemStack[] items) throws IllegalArgumentException; /** - * Checks if the inventory contains any ItemStacks with the given materialId + * Checks if the inventory contains any ItemStacks with the given + * materialId * * @param materialId The materialId to check for * @return true if an ItemStack in this inventory contains the materialId @@ -132,7 +138,8 @@ public interface Inventory extends Iterable<ItemStack> { public boolean contains(int materialId); /** - * Checks if the inventory contains any ItemStacks with the given material. + * Checks if the inventory contains any ItemStacks with the given + * material. * * @param material The material to check for * @return true if an ItemStack is found with the given Material @@ -141,31 +148,39 @@ public interface Inventory extends Iterable<ItemStack> { public boolean contains(Material material) throws IllegalArgumentException; /** - * Checks if the inventory contains any ItemStacks matching the given ItemStack. - * This will only return true if both the type and the amount of the stack match. + * Checks if the inventory contains any ItemStacks matching the given + * ItemStack. + * <p> + * This will only return true if both the type and the amount of the stack + * match. * * @param item The ItemStack to match against - * @return false if item is null, true if any exactly matching ItemStacks were found + * @return false if item is null, true if any exactly matching ItemStacks + * were found */ public boolean contains(ItemStack item); /** - * Checks if the inventory contains any ItemStacks with the given materialId, adding to at least the minimum amount specified. + * Checks if the inventory contains any ItemStacks with the given + * materialId, adding to at least the minimum amount specified. * * @param materialId The materialId to check for * @param amount The minimum amount to look for - * @return true if this contains any matching ItemStack with the given materialId and amount + * @return true if this contains any matching ItemStack with the given + * materialId and amount * @deprecated Magic value */ @Deprecated public boolean contains(int materialId, int amount); /** - * Checks if the inventory contains any ItemStacks with the given material, adding to at least the minimum amount specified. + * Checks if the inventory contains any ItemStacks with the given + * material, adding to at least the minimum amount specified. * * @param material The material to check for * @param amount The minimum amount - * @return true if amount is less than 1, true if enough ItemStacks were found to add to the given amount + * @return true if amount is less than 1, true if enough ItemStacks were + * found to add to the given amount * @throws IllegalArgumentException if material is null */ public boolean contains(Material material, int amount) throws IllegalArgumentException; @@ -226,12 +241,13 @@ public interface Inventory extends Iterable<ItemStack> { public HashMap<Integer, ? extends ItemStack> all(Material material) throws IllegalArgumentException; /** - * Finds all slots in the inventory containing any ItemStacks with the given ItemStack - * This will only match slots if both the type and the amount of the stack match + * Finds all slots in the inventory containing any ItemStacks with the + * given ItemStack. This will only match slots if both the type and the + * amount of the stack match * <p> - * The HashMap contains entries where, the key is the - * slot index, and the value is the ItemStack in that slot. If no matching - * ImemStrack with the given Material is found, an empty map is returned. + * The HashMap contains entries where, the key is the slot index, and the + * value is the ItemStack in that slot. If no matching ItemStack with the + * given Material is found, an empty map is returned. * * @param item The ItemStack to match against * @return A map from slot indexes to item at index @@ -239,7 +255,8 @@ public interface Inventory extends Iterable<ItemStack> { public HashMap<Integer, ? extends ItemStack> all(ItemStack item); /** - * Finds the first slot in the inventory containing an ItemStack with the given materialId. + * Finds the first slot in the inventory containing an ItemStack with the + * given materialId. * * @param materialId The materialId to look for * @return The slot index of the given materialId or -1 if not found @@ -249,7 +266,8 @@ public interface Inventory extends Iterable<ItemStack> { public int first(int materialId); /** - * Finds the first slot in the inventory containing an ItemStack with the given material + * Finds the first slot in the inventory containing an ItemStack with the + * given material * * @param material The material to look for * @return The slot index of the given Material or -1 if not found @@ -258,8 +276,9 @@ public interface Inventory extends Iterable<ItemStack> { public int first(Material material) throws IllegalArgumentException; /** - * Returns the first slot in the inventory containing an ItemStack with the given stack - * This will only match a slot if both the type and the amount of the stack match + * Returns the first slot in the inventory containing an ItemStack with + * the given stack. This will only match a slot if both the type and the + * amount of the stack match * * @param item The ItemStack to match against * @return The slot index of the given ItemStack or -1 if not found @@ -292,7 +311,9 @@ public interface Inventory extends Iterable<ItemStack> { /** * Removes all stacks in the inventory matching the given stack. - * This will only match a slot if both the type and the amount of the stack match + * <p> + * This will only match a slot if both the type and the amount of the + * stack match * * @param item The ItemStack to match against */ @@ -311,10 +332,12 @@ public interface Inventory extends Iterable<ItemStack> { public void clear(); /** - * Gets a list of players viewing. Note that a player is considered to be viewing their own - * inventory and internal crafting screen even when said inventory is not open. They will normally - * be considered to be viewing their inventory even when they have a different inventory screen open, - * but it's possible for customized inventory screens to exclude the viewer's inventory, so this should + * Gets a list of players viewing the inventory. Note that a player is + * considered to be viewing their own inventory and internal crafting + * screen even when said inventory is not open. They will normally be + * considered to be viewing their inventory even when they have a + * different inventory screen open, but it's possible for customized + * inventory screens to exclude the viewer's inventory, so this should * never be assumed to be non-empty. * * @return A list of HumanEntities who are viewing this Inventory. @@ -346,9 +369,10 @@ public interface Inventory extends Iterable<ItemStack> { public ListIterator<ItemStack> iterator(); /** - * Returns an iterator starting at the given index. If the index is positive, then the first - * call to next() will return the item at that index; if it is negative, the first call to - * previous will return the item at index (getSize() + index). + * Returns an iterator starting at the given index. If the index is + * positive, then the first call to next() will return the item at that + * index; if it is negative, the first call to previous will return the + * item at index (getSize() + index). * * @param index The index. * @return An iterator. diff --git a/src/main/java/org/bukkit/inventory/InventoryView.java b/src/main/java/org/bukkit/inventory/InventoryView.java index 490862a9..0427c569 100644 --- a/src/main/java/org/bukkit/inventory/InventoryView.java +++ b/src/main/java/org/bukkit/inventory/InventoryView.java @@ -4,12 +4,12 @@ import org.bukkit.entity.HumanEntity; import org.bukkit.event.inventory.InventoryType; /** - * Represents a view linking two inventories and a single player - * (whose inventory may or may not be one of the two) + * Represents a view linking two inventories and a single player (whose + * inventory may or may not be one of the two). * <p> * Note: If you implement this interface but fail to satisfy the expected - * contracts of certain methods, there's no guarantee that the game - * will work as it should. + * contracts of certain methods, there's no guarantee that the game will work + * as it should. */ public abstract class InventoryView { public final static int OUTSIDE = -999; @@ -34,15 +34,18 @@ public abstract class InventoryView { */ TICKS_FOR_CURRENT_FUEL(2, InventoryType.FURNACE), /** - * In an enchanting inventory, the top button's experience level value. + * In an enchanting inventory, the top button's experience level + * value. */ ENCHANT_BUTTON1(0, InventoryType.ENCHANTING), /** - * In an enchanting inventory, the middle button's experience level value. + * In an enchanting inventory, the middle button's experience level + * value. */ ENCHANT_BUTTON2(1, InventoryType.ENCHANTING), /** - * In an enchanting inventory, the bottom button's experience level value. + * In an enchanting inventory, the bottom button's experience level + * value. */ ENCHANT_BUTTON3(2, InventoryType.ENCHANTING); int id; @@ -87,9 +90,9 @@ public abstract class InventoryView { public abstract HumanEntity getPlayer(); /** - * Determine the type of inventory involved in the transaction. This indicates - * the window style being shown. It will never return PLAYER, since that is - * common to all windows. + * Determine the type of inventory involved in the transaction. This + * indicates the window style being shown. It will never return PLAYER, + * since that is common to all windows. * * @return the inventory type */ @@ -136,7 +139,8 @@ public abstract class InventoryView { /** * Sets the item on the cursor of one of the viewing players. * - * @param item The item to put on the cursor, or null to remove the item on their cursor. + * @param item The item to put on the cursor, or null to remove the item + * on their cursor. */ public final void setCursor(ItemStack item) { getPlayer().setItemOnCursor(item); @@ -145,18 +149,21 @@ public abstract class InventoryView { /** * Get the item on the cursor of one of the viewing players. * - * @return The item on the player's cursor, or null if they aren't holding one. + * @return The item on the player's cursor, or null if they aren't holding + * one. */ public final ItemStack getCursor() { return getPlayer().getItemOnCursor(); } /** - * Converts a raw slot ID into its local slot ID into whichever of the two inventories - * the slot points to. If the raw slot refers to the upper inventory, it will be returned - * unchanged and thus be suitable for getTopInventory().getItem(); if it refers to the - * lower inventory, the output will differ from the input and be suitable for - * getBottomInventory().getItem(). + * Converts a raw slot ID into its local slot ID into whichever of the two + * inventories the slot points to. + * <p> + * If the raw slot refers to the upper inventory, it will be returned + * unchanged and thus be suitable for getTopInventory().getItem(); if it + * refers to the lower inventory, the output will differ from the input + * and be suitable for getBottomInventory().getItem(). * * @param rawSlot The raw slot ID. * @return The converted slot ID. @@ -184,9 +191,11 @@ public abstract class InventoryView { } /** - * Check the total number of slots in this view, combining the upper and lower inventories. - * Note though that it's possible for this to be greater than the sum of the two inventories - * if for example some slots are not being used. + * Check the total number of slots in this view, combining the upper and + * lower inventories. + * <p> + * Note though that it's possible for this to be greater than the sum of + * the two inventories if for example some slots are not being used. * * @return The total size */ diff --git a/src/main/java/org/bukkit/inventory/ItemFactory.java b/src/main/java/org/bukkit/inventory/ItemFactory.java index 46d173d7..52a8d4d8 100644 --- a/src/main/java/org/bukkit/inventory/ItemFactory.java +++ b/src/main/java/org/bukkit/inventory/ItemFactory.java @@ -8,8 +8,11 @@ import org.bukkit.inventory.meta.ItemMeta; import org.bukkit.inventory.meta.SkullMeta; /** - * An instance of the ItemFactory can be obtained with {@link Server#getItemFactory()}. - * The ItemFactory is solely responsible for creating item meta containers to apply on item stacks. + * An instance of the ItemFactory can be obtained with {@link + * Server#getItemFactory()}. + * <p> + * The ItemFactory is solely responsible for creating item meta containers to + * apply on item stacks. */ public interface ItemFactory { @@ -17,29 +20,40 @@ public interface ItemFactory { * This creates a new item meta for the material. * * @param material The material to consider as base for the meta - * @return a new ItemMeta that could be applied to an item stack of the specified material + * @return a new ItemMeta that could be applied to an item stack of the + * specified material */ ItemMeta getItemMeta(final Material material); /** - * This method checks the item meta to confirm that it is applicable (no data lost if applied) to the specified ItemStack. - * A {@link SkullMeta} would not be valid for a sword, but a normal {@link ItemMeta} from an enchanted dirt block would. + * This method checks the item meta to confirm that it is applicable (no + * data lost if applied) to the specified ItemStack. + * <p> + * A {@link SkullMeta} would not be valid for a sword, but a normal {@link + * ItemMeta} from an enchanted dirt block would. * * @param meta Meta to check * @param stack Item that meta will be applied to - * @return true if the meta can be applied without losing data, false otherwise - * @throws IllegalArgumentException if the meta was not created by this factory + * @return true if the meta can be applied without losing data, false + * otherwise + * @throws IllegalArgumentException if the meta was not created by this + * factory */ boolean isApplicable(final ItemMeta meta, final ItemStack stack) throws IllegalArgumentException; /** - * This method checks the item meta to confirm that it is applicable (no data lost if applied) to the specified Material. - * A {@link SkullMeta} would not be valid for a sword, but a normal {@link ItemMeta} from an enchanted dirt block would. + * This method checks the item meta to confirm that it is applicable (no + * data lost if applied) to the specified Material. + * <p> + * A {@link SkullMeta} would not be valid for a sword, but a normal {@link + * ItemMeta} from an enchanted dirt block would. * * @param meta Meta to check * @param material Material that meta will be applied to - * @return true if the meta can be applied without losing data, false otherwise - * @throws IllegalArgumentException if the meta was not created by this factory + * @return true if the meta can be applied without losing data, false + * otherwise + * @throws IllegalArgumentException if the meta was not created by this + * factory */ boolean isApplicable(final ItemMeta meta, final Material material) throws IllegalArgumentException; @@ -47,42 +61,57 @@ public interface ItemFactory { * This method is used to compare two item meta data objects. * * @param meta1 First meta to compare, and may be null to indicate no data - * @param meta2 Second meta to compare, and may be null to indicate no data - * @return false if one of the meta has data the other does not, otherwise true - * @throws IllegalArgumentException if either meta was not created by this factory + * @param meta2 Second meta to compare, and may be null to indicate no + * data + * @return false if one of the meta has data the other does not, otherwise + * true + * @throws IllegalArgumentException if either meta was not created by this + * factory */ boolean equals(final ItemMeta meta1, final ItemMeta meta2) throws IllegalArgumentException; /** * Returns an appropriate item meta for the specified stack. - * - * The item meta returned will always be a valid meta for a given item stack of the specified material. - * It may be a more or less specific meta, and could also be the same meta or meta type as the parameter. - * The item meta returned will also always be the most appropriate meta. <br> - * <br> - * Example, if a {@link SkullMeta} is being applied to a book, this method would return a {@link BookMeta} containing all - * information in the specified meta that is applicable to an {@link ItemMeta}, the highest common interface. + * <p> + * The item meta returned will always be a valid meta for a given + * ItemStack of the specified material. It may be a more or less specific + * meta, and could also be the same meta or meta type as the parameter. + * The item meta returned will also always be the most appropriate meta. + * <p> + * Example, if a {@link SkullMeta} is being applied to a book, this method + * would return a {@link BookMeta} containing all information in the + * specified meta that is applicable to an {@link ItemMeta}, the highest + * common interface. * * @param meta the meta to convert * @param stack the stack to convert the meta for - * @return An appropriate item meta for the specified item stack. No guarantees are made as to if a copy is returned. This will be null for a stack of air. - * @throws IllegalArgumentException if the specified meta was not created by this factory + * @return An appropriate item meta for the specified item stack. No + * guarantees are made as to if a copy is returned. This will be null + * for a stack of air. + * @throws IllegalArgumentException if the specified meta was not created + * by this factory */ ItemMeta asMetaFor(final ItemMeta meta, final ItemStack stack) throws IllegalArgumentException; /** * Returns an appropriate item meta for the specified material. - * The item meta returned will always be a valid meta for a given item stack of the specified material. - * It may be a more or less specific meta, and could also be the same meta or meta type as the parameter. - * The item meta returned will also always be the most appropriate meta. <br> - * <br> - * Example, if a {@link SkullMeta} is being applied to a book, this method would return a {@link BookMeta} containing all - * information in the specified meta that is applicable to an {@link ItemMeta}, the highest common interface. + * <p> + * The item meta returned will always be a valid meta for a given + * ItemStack of the specified material. It may be a more or less specific + * meta, and could also be the same meta or meta type as the parameter. + * The item meta returned will also always be the most appropriate meta. + * <p> + * Example, if a {@link SkullMeta} is being applied to a book, this method + * would return a {@link BookMeta} containing all information in the + * specified meta that is applicable to an {@link ItemMeta}, the highest + * common interface. * * @param meta the meta to convert * @param material the material to convert the meta for - * @return An appropriate item meta for the specified item material. No guarantees are made as to if a copy is returned. This will be null for air. - * @throws IllegalArgumentException if the specified meta was not created by this factory + * @return An appropriate item meta for the specified item material. No + * guarantees are made as to if a copy is returned. This will be null for air. + * @throws IllegalArgumentException if the specified meta was not created + * by this factory */ ItemMeta asMetaFor(final ItemMeta meta, final Material material) throws IllegalArgumentException; diff --git a/src/main/java/org/bukkit/inventory/ItemStack.java b/src/main/java/org/bukkit/inventory/ItemStack.java index b5172bc4..6137c994 100644 --- a/src/main/java/org/bukkit/inventory/ItemStack.java +++ b/src/main/java/org/bukkit/inventory/ItemStack.java @@ -120,7 +120,8 @@ public class ItemStack implements Cloneable, ConfigurationSerializable { * Creates a new item stack derived from the specified stack * * @param stack the stack to copy - * @throws IllegalArgumentException if the specified stack is null or returns an item meta not created by the item factory + * @throws IllegalArgumentException if the specified stack is null or + * returns an item meta not created by the item factory */ public ItemStack(final ItemStack stack) throws IllegalArgumentException { Validate.notNull(stack, "Cannot copy null stack"); @@ -263,8 +264,8 @@ public class ItemStack implements Cloneable, ConfigurationSerializable { } /** - * Get the maximum stacksize for the material hold in this ItemStack - * Returns -1 if it has no idea. + * Get the maximum stacksize for the material hold in this ItemStack. + * (Returns -1 if it has no idea) * * @return The maximum you can stack this material to. */ @@ -312,7 +313,8 @@ public class ItemStack implements Cloneable, ConfigurationSerializable { } /** - * This method is the same as equals, but does not consider stack size (amount). + * This method is the same as equals, but does not consider stack size + * (amount). * * @param stack the item stack to compare to * @return true if the two stacks are equal, ignoring the amount @@ -392,13 +394,15 @@ public class ItemStack implements Cloneable, ConfigurationSerializable { /** * Adds the specified enchantments to this item stack. * <p> - * This method is the same as calling {@link #addEnchantment(org.bukkit.enchantments.Enchantment, int)} - * for each element of the map. + * This method is the same as calling {@link + * #addEnchantment(org.bukkit.enchantments.Enchantment, int)} for each + * element of the map. * * @param enchantments Enchantments to add * @throws IllegalArgumentException if the specified enchantments is null - * @throws IllegalArgumentException if any specific enchantment or level is null. - * <b>Warning</b>: Some enchantments may be added before this exception is thrown. + * @throws IllegalArgumentException if any specific enchantment or level + * is null. <b>Warning</b>: Some enchantments may be added before this + * exception is thrown. */ @Utility public void addEnchantments(Map<Enchantment, Integer> enchantments) { @@ -411,11 +415,13 @@ public class ItemStack implements Cloneable, ConfigurationSerializable { /** * Adds the specified {@link Enchantment} to this item stack. * <p> - * If this item stack already contained the given enchantment (at any level), it will be replaced. + * If this item stack already contained the given enchantment (at any + * level), it will be replaced. * * @param ench Enchantment to add * @param level Level of the enchantment - * @throws IllegalArgumentException if enchantment null, or enchantment is not applicable + * @throws IllegalArgumentException if enchantment null, or enchantment is + * not applicable */ @Utility public void addEnchantment(Enchantment ench, int level) { @@ -432,8 +438,9 @@ public class ItemStack implements Cloneable, ConfigurationSerializable { /** * Adds the specified enchantments to this item stack in an unsafe manner. * <p> - * This method is the same as calling {@link #addUnsafeEnchantment(org.bukkit.enchantments.Enchantment, int)} - * for each element of the map. + * This method is the same as calling {@link + * #addUnsafeEnchantment(org.bukkit.enchantments.Enchantment, int)} for + * each element of the map. * * @param enchantments Enchantments to add */ @@ -447,10 +454,11 @@ public class ItemStack implements Cloneable, ConfigurationSerializable { /** * Adds the specified {@link Enchantment} to this item stack. * <p> - * If this item stack already contained the given enchantment (at any level), it will be replaced. + * If this item stack already contained the given enchantment (at any + * level), it will be replaced. * <p> - * This method is unsafe and will ignore level restrictions or item type. Use at your own - * discretion. + * This method is unsafe and will ignore level restrictions or item type. + * Use at your own discretion. * * @param ench Enchantment to add * @param level Level of the enchantment @@ -460,7 +468,8 @@ public class ItemStack implements Cloneable, ConfigurationSerializable { } /** - * Removes the specified {@link Enchantment} if it exists on this item stack + * Removes the specified {@link Enchantment} if it exists on this + * ItemStack * * @param ench Enchantment to remove * @return Previous level, or 0 @@ -564,8 +573,10 @@ public class ItemStack implements Cloneable, ConfigurationSerializable { * Set the ItemMeta of this ItemStack. * * @param itemMeta new ItemMeta, or null to indicate meta data be cleared. - * @return True if successfully applied ItemMeta, see {@link ItemFactory#isApplicable(ItemMeta, ItemStack)} - * @throws IllegalArgumentException if the item meta was not created by the {@link ItemFactory} + * @return True if successfully applied ItemMeta, see {@link + * ItemFactory#isApplicable(ItemMeta, ItemStack)} + * @throws IllegalArgumentException if the item meta was not created by + * the {@link ItemFactory} */ public boolean setItemMeta(ItemMeta itemMeta) { return setItemMeta0(itemMeta, getType0()); diff --git a/src/main/java/org/bukkit/inventory/PlayerInventory.java b/src/main/java/org/bukkit/inventory/PlayerInventory.java index 7eb5c985..d18c9f40 100644 --- a/src/main/java/org/bukkit/inventory/PlayerInventory.java +++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java @@ -3,7 +3,7 @@ package org.bukkit.inventory; import org.bukkit.entity.HumanEntity; /** - * Includes interface to the 4 armor slots + * Interface to the inventory of a Player, including the four armor slots. */ public interface PlayerInventory extends Inventory { @@ -50,32 +50,32 @@ public interface PlayerInventory extends Inventory { public void setArmorContents(ItemStack[] items); /** - * Put the given ItemStack into the helmet slot - * This does not check if the ItemStack is a helmet + * Put the given ItemStack into the helmet slot. This does not check if + * the ItemStack is a helmet * * @param helmet The ItemStack to use as helmet */ public void setHelmet(ItemStack helmet); /** - * Put the given ItemStack into the chestplate slot - * This does not check if the ItemStack is a chestplate + * Put the given ItemStack into the chestplate slot. This does not check + * if the ItemStack is a chestplate * * @param chestplate The ItemStack to use as chestplate */ public void setChestplate(ItemStack chestplate); /** - * Put the given ItemStack into the leg slot - * This does not check if the ItemStack is a pair of leggings + * Put the given ItemStack into the leg slot. This does not check if the + * ItemStack is a pair of leggings * * @param leggings The ItemStack to use as leggings */ public void setLeggings(ItemStack leggings); /** - * Put the given ItemStack into the boots slot - * This does not check if the ItemStack is a boots + * Put the given ItemStack into the boots slot. This does not check if the + * ItemStack is a boots * * @param boots The ItemStack to use as boots */ @@ -108,13 +108,15 @@ public interface PlayerInventory extends Inventory { * This validates whether the slot is between 0 and 8 inclusive. * * @param slot The new slot number - * @throws IllegalArgumentException Thrown if slot is not between 0 and 8 inclusive + * @throws IllegalArgumentException Thrown if slot is not between 0 and 8 + * inclusive */ public void setHeldItemSlot(int slot); /** - * Clears all matching items from the inventory. Setting either value to -1 will skip it's check, - * while setting both to -1 will clear all items in your inventory unconditionally. + * Clears all matching items from the inventory. Setting either value to + * -1 will skip it's check, while setting both to -1 will clear all items + * in your inventory unconditionally. * * @param id the id of the item you want to clear from the inventory * @param data the data of the item you want to clear from the inventory diff --git a/src/main/java/org/bukkit/inventory/ShapedRecipe.java b/src/main/java/org/bukkit/inventory/ShapedRecipe.java index ce501355..2796473d 100644 --- a/src/main/java/org/bukkit/inventory/ShapedRecipe.java +++ b/src/main/java/org/bukkit/inventory/ShapedRecipe.java @@ -17,8 +17,9 @@ public class ShapedRecipe implements Recipe { private Map<Character, ItemStack> ingredients = new HashMap<Character, ItemStack>(); /** - * Create a shaped recipe to craft the specified ItemStack. The constructor merely determines the - * result and type; to set the actual recipe, you'll need to call the appropriate methods. + * Create a shaped recipe to craft the specified ItemStack. The + * constructor merely determines the result and type; to set the actual + * recipe, you'll need to call the appropriate methods. * * @param result The item you want the recipe to create. * @see ShapedRecipe#shape(String...) @@ -31,10 +32,12 @@ public class ShapedRecipe implements Recipe { } /** - * Set the shape of this recipe to the specified rows. Each character represents a different - * ingredient; exactly what each character represents is set separately. The first row supplied - * corresponds with the upper most part of the recipe on the workbench e.g. if all three - * rows are supplies the first string represents the top row on the workbench. + * Set the shape of this recipe to the specified rows. Each character + * represents a different ingredient; exactly what each character + * represents is set separately. The first row supplied corresponds with + * the upper most part of the recipe on the workbench e.g. if all three + * rows are supplies the first string represents the top row on the + * workbench. * * @param shape The rows of the recipe (up to 3 rows). * @return The changed recipe, so you can chain calls. diff --git a/src/main/java/org/bukkit/inventory/ShapelessRecipe.java b/src/main/java/org/bukkit/inventory/ShapelessRecipe.java index 83470ebb..a7180860 100644 --- a/src/main/java/org/bukkit/inventory/ShapelessRecipe.java +++ b/src/main/java/org/bukkit/inventory/ShapelessRecipe.java @@ -10,16 +10,17 @@ import org.bukkit.Material; import org.bukkit.material.MaterialData; /** - * Represents a shapeless recipe, where the arrangement of the ingredients on the crafting grid - * does not matter. + * Represents a shapeless recipe, where the arrangement of the ingredients on + * the crafting grid does not matter. */ public class ShapelessRecipe implements Recipe { private ItemStack output; private List<ItemStack> ingredients = new ArrayList<ItemStack>(); /** - * Create a shapeless recipe to craft the specified ItemStack. The constructor merely determines the - * result and type; to set the actual recipe, you'll need to call the appropriate methods. + * Create a shapeless recipe to craft the specified ItemStack. The + * constructor merely determines the result and type; to set the actual + * recipe, you'll need to call the appropriate methods. * * @param result The item you want the recipe to create. * @see ShapelessRecipe#addIngredient(Material) @@ -113,9 +114,9 @@ public class ShapelessRecipe implements Recipe { } /** - * Removes an ingredient from the list. If the ingredient occurs multiple times, - * only one instance of it is removed. Only removes exact matches, with a data value - * of 0. + * Removes an ingredient from the list. If the ingredient occurs multiple + * times, only one instance of it is removed. Only removes exact matches, + * with a data value of 0. * * @param ingredient The ingredient to remove * @return The changed recipe. @@ -125,9 +126,9 @@ public class ShapelessRecipe implements Recipe { } /** - * Removes an ingredient from the list. If the ingredient occurs multiple times, - * only one instance of it is removed. If the data value is -1, only ingredients - * with a -1 data value will be removed. + * Removes an ingredient from the list. If the ingredient occurs multiple + * times, only one instance of it is removed. If the data value is -1, + * only ingredients with a -1 data value will be removed. * * @param ingredient The ingredient to remove * @return The changed recipe. @@ -137,9 +138,9 @@ public class ShapelessRecipe implements Recipe { } /** - * Removes multiple instances of an ingredient from the list. If there are less instances - * then specified, all will be removed. Only removes exact matches, with a data value - * of 0. + * Removes multiple instances of an ingredient from the list. If there are + * less instances then specified, all will be removed. Only removes exact + * matches, with a data value of 0. * * @param count The number of copies to remove. * @param ingredient The ingredient to remove @@ -150,9 +151,9 @@ public class ShapelessRecipe implements Recipe { } /** - * Removes multiple instances of an ingredient from the list. If there are less instances - * then specified, all will be removed. If the data value is -1, only ingredients - * with a -1 data value will be removed. + * Removes multiple instances of an ingredient from the list. If there are + * less instances then specified, all will be removed. If the data value + * is -1, only ingredients with a -1 data value will be removed. * * @param count The number of copies to remove. * @param ingredient The ingredient to remove. @@ -163,9 +164,9 @@ public class ShapelessRecipe implements Recipe { } /** - * Removes an ingredient from the list. If the ingredient occurs multiple times, - * only one instance of it is removed. If the data value is -1, only ingredients - * with a -1 data value will be removed. + * Removes an ingredient from the list. If the ingredient occurs multiple + * times, only one instance of it is removed. If the data value is -1, + * only ingredients with a -1 data value will be removed. * * @param ingredient The ingredient to remove * @param rawdata The data value; @@ -178,9 +179,9 @@ public class ShapelessRecipe implements Recipe { } /** - * Removes multiple instances of an ingredient from the list. If there are less instances - * then specified, all will be removed. If the data value is -1, only ingredients - * with a -1 data value will be removed. + * Removes multiple instances of an ingredient from the list. If there are + * less instances then specified, all will be removed. If the data value + * is -1, only ingredients with a -1 data value will be removed. * * @param count The number of copies to remove. * @param ingredient The ingredient to remove. diff --git a/src/main/java/org/bukkit/inventory/meta/BookMeta.java b/src/main/java/org/bukkit/inventory/meta/BookMeta.java index 73148397..00175963 100644 --- a/src/main/java/org/bukkit/inventory/meta/BookMeta.java +++ b/src/main/java/org/bukkit/inventory/meta/BookMeta.java @@ -5,7 +5,8 @@ import java.util.List; import org.bukkit.Material; /** - * Represents a book ({@link Material#BOOK_AND_QUILL} or {@link Material#WRITTEN_BOOK}) that can have a title, an author, and pages. + * Represents a book ({@link Material#BOOK_AND_QUILL} or {@link + * Material#WRITTEN_BOOK}) that can have a title, an author, and pages. */ public interface BookMeta extends ItemMeta { @@ -18,14 +19,18 @@ public interface BookMeta extends ItemMeta { /** * Gets the title of the book. - * Plugins should check that hasTitle() returns true before calling this method. + * <p> + * Plugins should check that hasTitle() returns true before calling this + * method. * * @return the title of the book */ String getTitle(); /** - * Sets the title of the book. Limited to 16 characters. Removes title when given null. + * Sets the title of the book. + * <p> + * Limited to 16 characters. Removes title when given null. * * @param title the title to set * @return true if the title was successfully set @@ -41,7 +46,9 @@ public interface BookMeta extends ItemMeta { /** * Gets the author of the book. - * Plugins should check that hasAuthor() returns true before calling this method. + * <p> + * Plugins should check that hasAuthor() returns true before calling this + * method. * * @return the author of the book */ @@ -70,8 +77,11 @@ public interface BookMeta extends ItemMeta { String getPage(int page); /** - * Sets the specified page in the book. Pages of the book must be contiguous. - * The data can be up to 256 characters in length, additional characters are trucated. + * Sets the specified page in the book. Pages of the book must be + * contiguous. + * <p> + * The data can be up to 256 characters in length, additional characters + * are truncated. * * @param page the page number to set * @param data the data to set for that page @@ -86,21 +96,24 @@ public interface BookMeta extends ItemMeta { List<String> getPages(); /** - * Clears the existing book pages, and sets the book to use the provided pages. Maximum 50 pages with 256 characters per page. + * Clears the existing book pages, and sets the book to use the provided + * pages. Maximum 50 pages with 256 characters per page. * * @param pages A list of pages to set the book to use */ void setPages(List<String> pages); /** - * Clears the existing book pages, and sets the book to use the provided pages. Maximum 50 pages with 256 characters per page. + * Clears the existing book pages, and sets the book to use the provided + * pages. Maximum 50 pages with 256 characters per page. * * @param pages A list of strings, each being a page */ void setPages(String... pages); /** - * Adds new pages to the end of the book. Up to a maximum of 50 pages with 256 characters per page. + * Adds new pages to the end of the book. Up to a maximum of 50 pages with + * 256 characters per page. * * @param pages A list of strings, each being a page */ diff --git a/src/main/java/org/bukkit/inventory/meta/EnchantmentStorageMeta.java b/src/main/java/org/bukkit/inventory/meta/EnchantmentStorageMeta.java index 340087ff..fb93d030 100644 --- a/src/main/java/org/bukkit/inventory/meta/EnchantmentStorageMeta.java +++ b/src/main/java/org/bukkit/inventory/meta/EnchantmentStorageMeta.java @@ -6,8 +6,9 @@ import org.bukkit.Material; import org.bukkit.enchantments.Enchantment; /** - * EnchantmentMeta is specific to items that can <i>store</i> enchantments, as opposed to being enchanted. - * {@link Material#ENCHANTED_BOOK} is an example of an item with enchantment storage. + * EnchantmentMeta is specific to items that can <i>store</i> enchantments, as + * opposed to being enchanted. {@link Material#ENCHANTED_BOOK} is an example + * of an item with enchantment storage. */ public interface EnchantmentStorageMeta extends ItemMeta { @@ -30,7 +31,8 @@ public interface EnchantmentStorageMeta extends ItemMeta { * Checks for the level of the stored enchantment. * * @param ench enchantment to check - * @return The level that the specified stored enchantment has, or 0 if none + * @return The level that the specified stored enchantment has, or 0 if + * none */ int getStoredEnchantLevel(Enchantment ench); @@ -46,8 +48,10 @@ public interface EnchantmentStorageMeta extends ItemMeta { * * @param ench Enchantment to store * @param level Level for the enchantment - * @param ignoreLevelRestriction this indicates the enchantment should be applied, ignoring the level limit - * @return true if the item meta changed as a result of this call, false otherwise + * @param ignoreLevelRestriction this indicates the enchantment should be + * applied, ignoring the level limit + * @return true if the item meta changed as a result of this call, false + * otherwise * @throws IllegalArgumentException if enchantment is null */ boolean addStoredEnchant(Enchantment ench, int level, boolean ignoreLevelRestriction); @@ -56,13 +60,15 @@ public interface EnchantmentStorageMeta extends ItemMeta { * Remove the specified stored enchantment from this item meta. * * @param ench Enchantment to remove - * @return true if the item meta changed as a result of this call, false otherwise + * @return true if the item meta changed as a result of this call, false + * otherwise * @throws IllegalArgumentException if enchantment is null */ boolean removeStoredEnchant(Enchantment ench) throws IllegalArgumentException; /** - * Checks if the specified enchantment conflicts with any enchantments in this ItemMeta. + * Checks if the specified enchantment conflicts with any enchantments in + * this ItemMeta. * * @param ench enchantment to test * @return true if the enchantment conflicts, false otherwise diff --git a/src/main/java/org/bukkit/inventory/meta/FireworkEffectMeta.java b/src/main/java/org/bukkit/inventory/meta/FireworkEffectMeta.java index 37d4c36e..47046f16 100644 --- a/src/main/java/org/bukkit/inventory/meta/FireworkEffectMeta.java +++ b/src/main/java/org/bukkit/inventory/meta/FireworkEffectMeta.java @@ -4,7 +4,8 @@ import org.bukkit.FireworkEffect; import org.bukkit.Material; /** - * Represents a meta that can store a single FireworkEffect. An example includes {@link Material#FIREWORK_CHARGE}. + * Represents a meta that can store a single FireworkEffect. An example + * includes {@link Material#FIREWORK_CHARGE}. */ public interface FireworkEffectMeta extends ItemMeta { diff --git a/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java b/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java index aa7496c0..3e06ee04 100644 --- a/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java +++ b/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java @@ -23,16 +23,19 @@ public interface FireworkMeta extends ItemMeta { * * @param effects The firework effects to add * @throws IllegalArgumentException If effects is null - * @throws IllegalArgumentException If any effect is null (may be thrown after changes have occurred) + * @throws IllegalArgumentException If any effect is null (may be thrown + * after changes have occurred) */ void addEffects(FireworkEffect...effects) throws IllegalArgumentException; /** * Add several firework effects to this firework. * - * @param effects An iterable object whose iterator yields the desired firework effects + * @param effects An iterable object whose iterator yields the desired + * firework effects * @throws IllegalArgumentException If effects is null - * @throws IllegalArgumentException If any effect is null (may be thrown after changes have occurred) + * @throws IllegalArgumentException If any effect is null (may be thrown + * after changes have occurred) */ void addEffects(Iterable<FireworkEffect> effects) throws IllegalArgumentException; @@ -54,7 +57,8 @@ public interface FireworkMeta extends ItemMeta { * Remove an effect from this firework. * * @param index The index of the effect to remove - * @throws IndexOutOfBoundsException If index < 0 or index > {@link #getEffectsSize()} + * @throws IndexOutOfBoundsException If index < 0 or index > {@link + * #getEffectsSize()} */ void removeEffect(int index) throws IndexOutOfBoundsException; @@ -78,7 +82,8 @@ public interface FireworkMeta extends ItemMeta { int getPower(); /** - * Sets the approximate power of the firework. Each level of power is half a second of flight time. + * Sets the approximate power of the firework. Each level of power is half + * a second of flight time. * * @param power the power of the firework, from 0-128 * @throws IllegalArgumentException if height<0 or height>128 diff --git a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java index 3dafdc09..397ba115 100644 --- a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java +++ b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java @@ -8,6 +8,7 @@ import org.bukkit.enchantments.Enchantment; /** * This type represents the storage mechanism for auxiliary item data. + * <p> * An implementation will handle the creation and application for ItemMeta. * This class should not be implemented by a plugin in a live environment. */ @@ -22,7 +23,9 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable { /** * Gets the display name that is set. - * Plugins should check that hasDisplayName() returns <code>true</code> before calling this method. + * <p> + * Plugins should check that hasDisplayName() returns <code>true</code> + * before calling this method. * * @return the display name that is set */ @@ -44,7 +47,9 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable { /** * Gets the lore that is set. - * Plugins should check if hasLore() returns <code>true</code> before calling this method. + * <p> + * Plugins should check if hasLore() returns <code>true</code> before + * calling this method. * * @return a list of lore that is set */ @@ -94,8 +99,10 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable { * * @param ench Enchantment to add * @param level Level for the enchantment - * @param ignoreLevelRestriction this indicates the enchantment should be applied, ignoring the level limit - * @return true if the item meta changed as a result of this call, false otherwise + * @param ignoreLevelRestriction this indicates the enchantment should be + * applied, ignoring the level limit + * @return true if the item meta changed as a result of this call, false + * otherwise */ boolean addEnchant(Enchantment ench, int level, boolean ignoreLevelRestriction); @@ -103,12 +110,14 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable { * Removes the specified enchantment from this item meta. * * @param ench Enchantment to remove - * @return true if the item meta changed as a result of this call, false otherwise + * @return true if the item meta changed as a result of this call, false + * otherwise */ boolean removeEnchant(Enchantment ench); /** - * Checks if the specified enchantment conflicts with any enchantments in this ItemMeta. + * Checks if the specified enchantment conflicts with any enchantments in + * this ItemMeta. * * @param ench enchantment to test * @return true if the enchantment conflicts, false otherwise diff --git a/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java b/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java index 01e23336..2dc24204 100644 --- a/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java +++ b/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java @@ -5,12 +5,15 @@ import org.bukkit.Material; import org.bukkit.inventory.ItemFactory; /** - * Represents leather armor ({@link Material#LEATHER_BOOTS}, {@link Material#LEATHER_CHESTPLATE}, {@link Material#LEATHER_HELMET}, or {@link Material#LEATHER_LEGGINGS}) that can be colored. + * Represents leather armor ({@link Material#LEATHER_BOOTS}, {@link + * Material#LEATHER_CHESTPLATE}, {@link Material#LEATHER_HELMET}, or {@link + * Material#LEATHER_LEGGINGS}) that can be colored. */ public interface LeatherArmorMeta extends ItemMeta { /** - * Gets the color of the armor. If it has not been set otherwise, it will be {@link ItemFactory#getDefaultLeatherColor()}. + * Gets the color of the armor. If it has not been set otherwise, it will + * be {@link ItemFactory#getDefaultLeatherColor()}. * * @return the color of the armor, never null */ @@ -19,7 +22,8 @@ public interface LeatherArmorMeta extends ItemMeta { /** * Sets the color of the armor. * - * @param color the color to set. Setting it to null is equivalent to setting it to {@link ItemFactory#getDefaultLeatherColor()}. + * @param color the color to set. Setting it to null is equivalent to + * setting it to {@link ItemFactory#getDefaultLeatherColor()}. */ void setColor(Color color); diff --git a/src/main/java/org/bukkit/inventory/meta/PotionMeta.java b/src/main/java/org/bukkit/inventory/meta/PotionMeta.java index de7d5e82..8dca9830 100644 --- a/src/main/java/org/bukkit/inventory/meta/PotionMeta.java +++ b/src/main/java/org/bukkit/inventory/meta/PotionMeta.java @@ -19,8 +19,11 @@ public interface PotionMeta extends ItemMeta { boolean hasCustomEffects(); /** - * Gets an immutable list containing all custom potion effects applied to this potion. - * Plugins should check that hasCustomEffects() returns true before calling this method. + * Gets an immutable list containing all custom potion effects applied to + * this potion. + * <p> + * Plugins should check that hasCustomEffects() returns true before + * calling this method. * * @return the immutable list of custom potion effects */ @@ -30,7 +33,8 @@ public interface PotionMeta extends ItemMeta { * Adds a custom potion effect to this potion. * * @param effect the potion effect to add - * @param overwrite true if any existing effect of the same type should be overwritten + * @param overwrite true if any existing effect of the same type should be + * overwritten * @return true if the potion meta changed as a result of this call */ boolean addCustomEffect(PotionEffect effect, boolean overwrite); @@ -53,7 +57,9 @@ public interface PotionMeta extends ItemMeta { /** * Moves a potion effect to the top of the potion effect list. - * This causes the client to display the potion effect in the potion's name. + * <p> + * This causes the client to display the potion effect in the potion's + * name. * * @param type the potion effect type to move * @return true if the potion meta changed as a result of this call diff --git a/src/main/java/org/bukkit/inventory/meta/SkullMeta.java b/src/main/java/org/bukkit/inventory/meta/SkullMeta.java index f8aab18d..fab31190 100644 --- a/src/main/java/org/bukkit/inventory/meta/SkullMeta.java +++ b/src/main/java/org/bukkit/inventory/meta/SkullMeta.java @@ -23,7 +23,9 @@ public interface SkullMeta extends ItemMeta { /** * Sets the owner of the skull. - * Plugins should check that hasOwner() returns true before calling this plugin. + * <p> + * Plugins should check that hasOwner() returns true before calling this + * plugin. * * @param owner the new owner of the skull * @return true if the owner was successfully set diff --git a/src/main/java/org/bukkit/map/MapCanvas.java b/src/main/java/org/bukkit/map/MapCanvas.java index f75e2093..d68bb179 100644 --- a/src/main/java/org/bukkit/map/MapCanvas.java +++ b/src/main/java/org/bukkit/map/MapCanvas.java @@ -4,7 +4,8 @@ import java.awt.Image; /** * Represents a canvas for drawing to a map. Each canvas is associated with a - * specific {@link MapRenderer} and represents that renderer's layer on the map. + * specific {@link MapRenderer} and represents that renderer's layer on the + * map. */ public interface MapCanvas { diff --git a/src/main/java/org/bukkit/map/MapCursor.java b/src/main/java/org/bukkit/map/MapCursor.java index ad002b7b..d3698a6e 100644 --- a/src/main/java/org/bukkit/map/MapCursor.java +++ b/src/main/java/org/bukkit/map/MapCursor.java @@ -146,9 +146,10 @@ public final class MapCursor { } /** - * Represents the standard types of map cursors. More may be made available - * by texture packs - the value is used by the client as an index in the - * file './misc/mapicons.png' from minecraft.jar or from a texture pack. + * Represents the standard types of map cursors. More may be made + * available by texture packs - the value is used by the client as an + * index in the file './misc/mapicons.png' from minecraft.jar or from a + * texture pack. */ public enum Type { WHITE_POINTER(0), diff --git a/src/main/java/org/bukkit/map/MapFont.java b/src/main/java/org/bukkit/map/MapFont.java index a6016ffc..84c809f7 100644 --- a/src/main/java/org/bukkit/map/MapFont.java +++ b/src/main/java/org/bukkit/map/MapFont.java @@ -33,14 +33,16 @@ public class MapFont { * Get the sprite for a given character. * * @param ch The character to get the sprite for. - * @return The CharacterSprite associated with the character, or null if there is none. + * @return The CharacterSprite associated with the character, or null if + * there is none. */ public CharacterSprite getChar(char ch) { return chars.get(ch); } /** - * Get the width of the given text as it would be rendered using this font. + * Get the width of the given text as it would be rendered using this + * font. * * @param text The text. * @return The width in pixels. @@ -70,7 +72,8 @@ public class MapFont { * Check whether the given text is valid. * * @param text The text. - * @return True if the string contains only defined characters, false otherwise. + * @return True if the string contains only defined characters, false + * otherwise. */ public boolean isValid(String text) { for (int i = 0; i < text.length(); ++i) { diff --git a/src/main/java/org/bukkit/map/MapPalette.java b/src/main/java/org/bukkit/map/MapPalette.java index f5d6f325..35f3e19b 100644 --- a/src/main/java/org/bukkit/map/MapPalette.java +++ b/src/main/java/org/bukkit/map/MapPalette.java @@ -181,7 +181,8 @@ public final class MapPalette { } /** - * Get the index of the closest matching color in the palette to the given color. + * Get the index of the closest matching color in the palette to the given + * color. * * @param r The red component of the color. * @param b The blue component of the color. @@ -195,7 +196,8 @@ public final class MapPalette { } /** - * Get the index of the closest matching color in the palette to the given color. + * Get the index of the closest matching color in the palette to the given + * color. * * @param color The Color to match. * @return The index in the palette. diff --git a/src/main/java/org/bukkit/map/MapRenderer.java b/src/main/java/org/bukkit/map/MapRenderer.java index 08f134a9..322d0ce3 100644 --- a/src/main/java/org/bukkit/map/MapRenderer.java +++ b/src/main/java/org/bukkit/map/MapRenderer.java @@ -10,7 +10,8 @@ public abstract class MapRenderer { private boolean contextual; /** - * Initialize the map renderer base to be non-contextual. See {@link #isContextual()}. + * Initialize the map renderer base to be non-contextual. See {@link + * #isContextual()}. */ public MapRenderer() { this(false); @@ -19,7 +20,8 @@ public abstract class MapRenderer { /** * Initialize the map renderer base with the given contextual status. * - * @param contextual Whether the renderer is contextual. See {@link #isContextual()}. + * @param contextual Whether the renderer is contextual. See {@link + * #isContextual()}. */ public MapRenderer(boolean contextual) { this.contextual = contextual; diff --git a/src/main/java/org/bukkit/material/Door.java b/src/main/java/org/bukkit/material/Door.java index 2bebf9bb..65fa32ca 100644 --- a/src/main/java/org/bukkit/material/Door.java +++ b/src/main/java/org/bukkit/material/Door.java @@ -69,7 +69,7 @@ public class Door extends MaterialData implements Directional, Openable { } /** - * Configure this part of the door to be either the top or the bottom half; + * Configure this part of the door to be either the top or the bottom half * * @param isTopHalf True to make it the top half. * @deprecated Shouldn't be used anymore diff --git a/src/main/java/org/bukkit/material/ExtendedRails.java b/src/main/java/org/bukkit/material/ExtendedRails.java index 87234bbd..0dbbf7c8 100644 --- a/src/main/java/org/bukkit/material/ExtendedRails.java +++ b/src/main/java/org/bukkit/material/ExtendedRails.java @@ -4,7 +4,8 @@ import org.bukkit.Material; import org.bukkit.block.BlockFace; /** - * This is the superclass for the {@link DetectorRail} and {@link PoweredRail} classes + * This is the superclass for the {@link DetectorRail} and {@link PoweredRail} + * classes */ public class ExtendedRails extends Rails { /** diff --git a/src/main/java/org/bukkit/material/FlowerPot.java b/src/main/java/org/bukkit/material/FlowerPot.java index 986de7e6..787c58d2 100644 --- a/src/main/java/org/bukkit/material/FlowerPot.java +++ b/src/main/java/org/bukkit/material/FlowerPot.java @@ -50,7 +50,8 @@ public class FlowerPot extends MaterialData { /** * Get the material in the flower pot * - * @return material MaterialData for the block currently in the flower pot or null if empty + * @return material MaterialData for the block currently in the flower pot + * or null if empty */ public MaterialData getContents() { switch (getData()) { diff --git a/src/main/java/org/bukkit/material/FurnaceAndDispenser.java b/src/main/java/org/bukkit/material/FurnaceAndDispenser.java index a99fac5d..3665479f 100644 --- a/src/main/java/org/bukkit/material/FurnaceAndDispenser.java +++ b/src/main/java/org/bukkit/material/FurnaceAndDispenser.java @@ -6,6 +6,7 @@ import org.bukkit.Material; * Represents a furnace or dispenser, two types of directional containers */ public class FurnaceAndDispenser extends DirectionalContainer { + /** * * @deprecated Magic value diff --git a/src/main/java/org/bukkit/material/Mushroom.java b/src/main/java/org/bukkit/material/Mushroom.java index f38f71f8..716d3781 100644 --- a/src/main/java/org/bukkit/material/Mushroom.java +++ b/src/main/java/org/bukkit/material/Mushroom.java @@ -90,11 +90,13 @@ public class Mushroom extends MaterialData { } /** - * Set a face of the block to be painted or not. Note that due to the nature of how the data is stored, - * setting a face painted or not is not guaranteed to leave the other faces unchanged. + * Set a face of the block to be painted or not. Note that due to the + * nature of how the data is stored, setting a face painted or not is not + * guaranteed to leave the other faces unchanged. * * @param face The face to paint or unpaint. - * @param painted True if you want to paint it, false if you want the pores to show. + * @param painted True if you want to paint it, false if you want the + * pores to show. */ public void setFacePainted(BlockFace face, boolean painted) { if (painted == isFacePainted(face)) { @@ -154,7 +156,8 @@ public class Mushroom extends MaterialData { } /** - * @return A set of all faces that are currently painted (an empty set if it is a stem) + * @return A set of all faces that are currently painted (an empty set if + * it is a stem) */ public Set<BlockFace> getPaintedFaces() { EnumSet<BlockFace> faces = EnumSet.noneOf(BlockFace.class); diff --git a/src/main/java/org/bukkit/material/NetherWarts.java b/src/main/java/org/bukkit/material/NetherWarts.java index 49fc5d71..99ea3f0b 100644 --- a/src/main/java/org/bukkit/material/NetherWarts.java +++ b/src/main/java/org/bukkit/material/NetherWarts.java @@ -1,99 +1,99 @@ -package org.bukkit.material;
-
-import org.bukkit.Material;
-import org.bukkit.NetherWartsState;
-
-/**
- * Represents nether wart
- */
-public class NetherWarts extends MaterialData {
- public NetherWarts() {
- super(Material.NETHER_WARTS);
- }
-
- public NetherWarts(NetherWartsState state) {
- this();
- setState(state);
- }
-
- /**
- *
- * @deprecated Magic value
- */
- @Deprecated
- public NetherWarts(final int type) {
- super(type);
- }
-
- public NetherWarts(final Material type) {
- super (type);
- }
-
- /**
- *
- * @deprecated Magic value
- */
- @Deprecated
- public NetherWarts(final int type, final byte data) {
- super(type, data);
- }
-
- /**
- *
- * @deprecated Magic value
- */
- @Deprecated
- public NetherWarts(final Material type, final byte data) {
- super(type, data);
- }
-
- /**
- * Gets the current growth state of this nether wart
- *
- * @return NetherWartsState of this nether wart
- */
- public NetherWartsState getState() {
- switch (getData()) {
- case 0:
- return NetherWartsState.SEEDED;
- case 1:
- return NetherWartsState.STAGE_ONE;
- case 2:
- return NetherWartsState.STAGE_TWO;
- default:
- return NetherWartsState.RIPE;
- }
- }
-
- /**
- * Sets the growth state of this nether wart
- *
- * @param state New growth state of this nether wart
- */
- public void setState(NetherWartsState state) {
- switch (state) {
- case SEEDED:
- setData((byte) 0x0);
- return;
- case STAGE_ONE:
- setData((byte) 0x1);
- return;
- case STAGE_TWO:
- setData((byte) 0x2);
- return;
- case RIPE:
- setData((byte) 0x3);
- return;
- }
- }
-
- @Override
- public String toString() {
- return getState() + " " + super.toString();
- }
-
- @Override
- public NetherWarts clone() {
- return (NetherWarts) super.clone();
- }
-}
+package org.bukkit.material; + +import org.bukkit.Material; +import org.bukkit.NetherWartsState; + +/** + * Represents nether wart + */ +public class NetherWarts extends MaterialData { + public NetherWarts() { + super(Material.NETHER_WARTS); + } + + public NetherWarts(NetherWartsState state) { + this(); + setState(state); + } + + /** + * + * @deprecated Magic value + */ + @Deprecated + public NetherWarts(final int type) { + super(type); + } + + public NetherWarts(final Material type) { + super (type); + } + + /** + * + * @deprecated Magic value + */ + @Deprecated + public NetherWarts(final int type, final byte data) { + super(type, data); + } + + /** + * + * @deprecated Magic value + */ + @Deprecated + public NetherWarts(final Material type, final byte data) { + super(type, data); + } + + /** + * Gets the current growth state of this nether wart + * + * @return NetherWartsState of this nether wart + */ + public NetherWartsState getState() { + switch (getData()) { + case 0: + return NetherWartsState.SEEDED; + case 1: + return NetherWartsState.STAGE_ONE; + case 2: + return NetherWartsState.STAGE_TWO; + default: + return NetherWartsState.RIPE; + } + } + + /** + * Sets the growth state of this nether wart + * + * @param state New growth state of this nether wart + */ + public void setState(NetherWartsState state) { + switch (state) { + case SEEDED: + setData((byte) 0x0); + return; + case STAGE_ONE: + setData((byte) 0x1); + return; + case STAGE_TWO: + setData((byte) 0x2); + return; + case RIPE: + setData((byte) 0x3); + return; + } + } + + @Override + public String toString() { + return getState() + " " + super.toString(); + } + + @Override + public NetherWarts clone() { + return (NetherWarts) super.clone(); + } +} diff --git a/src/main/java/org/bukkit/material/Openable.java b/src/main/java/org/bukkit/material/Openable.java index 17e5f022..0ae54f97 100644 --- a/src/main/java/org/bukkit/material/Openable.java +++ b/src/main/java/org/bukkit/material/Openable.java @@ -1,6 +1,7 @@ package org.bukkit.material; public interface Openable { + /** * Check to see if the door is open. * diff --git a/src/main/java/org/bukkit/material/Rails.java b/src/main/java/org/bukkit/material/Rails.java index 969ccc49..74fd95a9 100644 --- a/src/main/java/org/bukkit/material/Rails.java +++ b/src/main/java/org/bukkit/material/Rails.java @@ -62,11 +62,11 @@ public class Rails extends MaterialData { } /** - * @return the direction these tracks are set <br> - * Note that tracks are bidirectional and that the direction - * returned is the ascending direction if the track is set on a - * slope. If it is set as a curve, the corner of the track is - * returned. + * @return the direction these tracks are set + * <p> + * Note that tracks are bidirectional and that the direction returned + * is the ascending direction if the track is set on a slope. If it is + * set as a curve, the corner of the track is returned. */ public BlockFace getDirection() { byte d = getConvertedData(); @@ -111,7 +111,9 @@ public class Rails extends MaterialData { } /** - * Return the data without the extended properties used by {@link PoweredRail} and {@link DetectorRail}. Overridden in {@link ExtendedRails} + * Return the data without the extended properties used by {@link + * PoweredRail} and {@link DetectorRail}. Overridden in {@link + * ExtendedRails} * * @return the data without the extended part * @deprecated Magic value @@ -122,11 +124,11 @@ public class Rails extends MaterialData { } /** - * Set the direction of these tracks<br> - * Note that tracks are bidirectional and that the direction - * returned is the ascending direction if the track is set on a - * slope. If it is set as a curve, the corner of the track should - * be supplied. + * Set the direction of these tracks + * <p> + * Note that tracks are bidirectional and that the direction returned is + * the ascending direction if the track is set on a slope. If it is set as + * a curve, the corner of the track should be supplied. * * @param face the direction the track should be facing * @param isOnSlope whether or not the track should be on a slope diff --git a/src/main/java/org/bukkit/material/Sign.java b/src/main/java/org/bukkit/material/Sign.java index 21f3dba2..e8da7aa9 100644 --- a/src/main/java/org/bukkit/material/Sign.java +++ b/src/main/java/org/bukkit/material/Sign.java @@ -45,8 +45,8 @@ public class Sign extends MaterialData implements Attachable { /** * Check if this sign is attached to a wall * - * @return true if this sign is attached to a wall, false if set on top of a - * block + * @return true if this sign is attached to a wall, false if set on top of + * a block */ public boolean isWallSign() { return getItemType() == Material.WALL_SIGN; diff --git a/src/main/java/org/bukkit/material/Stairs.java b/src/main/java/org/bukkit/material/Stairs.java index 1980174e..1f73c77c 100644 --- a/src/main/java/org/bukkit/material/Stairs.java +++ b/src/main/java/org/bukkit/material/Stairs.java @@ -115,7 +115,8 @@ public class Stairs extends MaterialData implements Directional { /** * Set step inverted state * - * @param inv - true if step is inverted (top half), false if step is normal (bottom half) + * @param inv - true if step is inverted (top half), false if step is + * normal (bottom half) */ public void setInverted(boolean inv) { int dat = getData() & 0x3; diff --git a/src/main/java/org/bukkit/material/Step.java b/src/main/java/org/bukkit/material/Step.java index e3f509b6..605f817c 100644 --- a/src/main/java/org/bukkit/material/Step.java +++ b/src/main/java/org/bukkit/material/Step.java @@ -76,7 +76,8 @@ public class Step extends TexturedMaterial { /** * Set step inverted state * - * @param inv - true if step is inverted (top half), false if step is normal (bottom half) + * @param inv - true if step is inverted (top half), false if step is + * normal (bottom half) */ public void setInverted(boolean inv) { int dat = getData() & 0x7; diff --git a/src/main/java/org/bukkit/material/TexturedMaterial.java b/src/main/java/org/bukkit/material/TexturedMaterial.java index 08cbbb64..cfd971bd 100644 --- a/src/main/java/org/bukkit/material/TexturedMaterial.java +++ b/src/main/java/org/bukkit/material/TexturedMaterial.java @@ -41,7 +41,8 @@ public abstract class TexturedMaterial extends MaterialData { } /** - * Retrieve a list of possible textures. The first element of the list will be used as a default. + * Retrieve a list of possible textures. The first element of the list + * will be used as a default. * * @return a list of possible textures for this block */ diff --git a/src/main/java/org/bukkit/material/Tree.java b/src/main/java/org/bukkit/material/Tree.java index 54ae5167..fe568723 100644 --- a/src/main/java/org/bukkit/material/Tree.java +++ b/src/main/java/org/bukkit/material/Tree.java @@ -75,7 +75,13 @@ public class Tree extends MaterialData { /** * Get direction of the log * - * @return BlockFace.TOP for upright (default), BlockFace.NORTH (east-west), BlockFace.WEST (north-sout), BlockFace.SELF (directionless) + * @return one of: + * <ul> + * <li>BlockFace.TOP for upright (default) + * <li>BlockFace.NORTH (east-west) + * <li>BlockFace.WEST (north-south) + * <li>BlockFace.SELF (directionless) + * </ul> */ public BlockFace getDirection() { switch ((getData() >> 2) & 0x3) { diff --git a/src/main/java/org/bukkit/material/Vine.java b/src/main/java/org/bukkit/material/Vine.java index 83de4e06..a4f7ad57 100644 --- a/src/main/java/org/bukkit/material/Vine.java +++ b/src/main/java/org/bukkit/material/Vine.java @@ -68,8 +68,9 @@ public class Vine extends MaterialData { } /** - * Check if the vine is attached to the specified face of an adjacent block. You can - * check two faces at once by passing eg {@link BlockFace#NORTH_EAST}. + * Check if the vine is attached to the specified face of an adjacent + * block. You can check two faces at once by passing e.g. {@link + * BlockFace#NORTH_EAST}. * * @param face The face to check. * @return Whether it is attached to that face. diff --git a/src/main/java/org/bukkit/material/WoodenStep.java b/src/main/java/org/bukkit/material/WoodenStep.java index c6f57a27..9584e252 100644 --- a/src/main/java/org/bukkit/material/WoodenStep.java +++ b/src/main/java/org/bukkit/material/WoodenStep.java @@ -80,7 +80,8 @@ public class WoodenStep extends MaterialData { /** * Set step inverted state * - * @param inv - true if step is inverted (top half), false if step is normal (bottom half) + * @param inv - true if step is inverted (top half), false if step is + * normal (bottom half) */ public void setInverted(boolean inv) { int dat = getData() & 0x7; diff --git a/src/main/java/org/bukkit/metadata/FixedMetadataValue.java b/src/main/java/org/bukkit/metadata/FixedMetadataValue.java index f23ad606..bce6f000 100644 --- a/src/main/java/org/bukkit/metadata/FixedMetadataValue.java +++ b/src/main/java/org/bukkit/metadata/FixedMetadataValue.java @@ -5,21 +5,26 @@ import org.bukkit.plugin.Plugin; import java.util.concurrent.Callable; /** - * A FixedMetadataValue is a special case metadata item that contains the same value forever after initialization. - * Invalidating a FixedMetadataValue has no effect. + * A FixedMetadataValue is a special case metadata item that contains the same + * value forever after initialization. Invalidating a FixedMetadataValue has + * no effect. * <p> - * This class extends LazyMetadataValue for historical reasons, even though it overrides all the implementation - * methods. it is possible that in the future that the inheritance hierarchy may change. + * This class extends LazyMetadataValue for historical reasons, even though it + * overrides all the implementation methods. it is possible that in the future + * that the inheritance hierarchy may change. */ public class FixedMetadataValue extends LazyMetadataValue { - /** Store the internal value that is represented by this fixed value. */ + + /** + * Store the internal value that is represented by this fixed value. + */ private final Object internalValue; /** * Initializes a FixedMetadataValue with an Object * - * @param owningPlugin the {@link Plugin} that created this metadata value. - * @param value the value assigned to this metadata value. + * @param owningPlugin the {@link Plugin} that created this metadata value + * @param value the value assigned to this metadata value */ public FixedMetadataValue(Plugin owningPlugin, final Object value) { super(owningPlugin); diff --git a/src/main/java/org/bukkit/metadata/LazyMetadataValue.java b/src/main/java/org/bukkit/metadata/LazyMetadataValue.java index d67e633c..a9546e53 100644 --- a/src/main/java/org/bukkit/metadata/LazyMetadataValue.java +++ b/src/main/java/org/bukkit/metadata/LazyMetadataValue.java @@ -7,10 +7,14 @@ import org.apache.commons.lang.Validate; import org.bukkit.plugin.Plugin; /** - * The LazyMetadataValue class implements a type of metadata that is not computed until another plugin asks for it. - * By making metadata values lazy, no computation is done by the providing plugin until absolutely necessary (if ever). - * Additionally, LazyMetadataValue objects cache their values internally unless overridden by a {@link CacheStrategy} - * or invalidated at the individual or plugin level. Once invalidated, the LazyMetadataValue will recompute its value + * The LazyMetadataValue class implements a type of metadata that is not + * computed until another plugin asks for it. + * <p> + * By making metadata values lazy, no computation is done by the providing + * plugin until absolutely necessary (if ever). Additionally, + * LazyMetadataValue objects cache their values internally unless overridden + * by a {@link CacheStrategy} or invalidated at the individual or plugin + * level. Once invalidated, the LazyMetadataValue will recompute its value * when asked. */ public class LazyMetadataValue extends MetadataValueAdapter implements MetadataValue { @@ -20,9 +24,11 @@ public class LazyMetadataValue extends MetadataValueAdapter implements MetadataV private static final Object ACTUALLY_NULL = new Object(); /** - * Initialized a LazyMetadataValue object with the default CACHE_AFTER_FIRST_EVAL cache strategy. + * Initialized a LazyMetadataValue object with the default + * CACHE_AFTER_FIRST_EVAL cache strategy. * - * @param owningPlugin the {@link Plugin} that created this metadata value. + * @param owningPlugin the {@link Plugin} that created this metadata + * value. * @param lazyValue the lazy value assigned to this metadata value. */ public LazyMetadataValue(Plugin owningPlugin, Callable<Object> lazyValue) { @@ -32,8 +38,10 @@ public class LazyMetadataValue extends MetadataValueAdapter implements MetadataV /** * Initializes a LazyMetadataValue object with a specific cache strategy. * - * @param owningPlugin the {@link Plugin} that created this metadata value. - * @param cacheStrategy determines the rules for caching this metadata value. + * @param owningPlugin the {@link Plugin} that created this metadata + * value. + * @param cacheStrategy determines the rules for caching this metadata + * value. * @param lazyValue the lazy value assigned to this metadata value. */ public LazyMetadataValue(Plugin owningPlugin, CacheStrategy cacheStrategy, Callable<Object> lazyValue) { @@ -45,7 +53,10 @@ public class LazyMetadataValue extends MetadataValueAdapter implements MetadataV this.cacheStrategy = cacheStrategy; } - /** Protected special constructor used by FixedMetadataValue to bypass standard setup. */ + /** + * Protected special constructor used by FixedMetadataValue to bypass + * standard setup. + */ protected LazyMetadataValue(Plugin owningPlugin) { super(owningPlugin); } @@ -62,7 +73,8 @@ public class LazyMetadataValue extends MetadataValueAdapter implements MetadataV /** * Lazily evaluates the value of this metadata item. * - * @throws MetadataEvaluationException if computing the metadata value fails. + * @throws MetadataEvaluationException if computing the metadata value + * fails. */ private synchronized void eval() throws MetadataEvaluationException { if (cacheStrategy == CacheStrategy.NEVER_CACHE || internalValue.get() == null) { @@ -89,7 +101,8 @@ public class LazyMetadataValue extends MetadataValueAdapter implements MetadataV */ public enum CacheStrategy { /** - * Once the metadata value has been evaluated, do not re-evaluate the value until it is manually invalidated. + * Once the metadata value has been evaluated, do not re-evaluate the + * value until it is manually invalidated. */ CACHE_AFTER_FIRST_EVAL, @@ -99,7 +112,8 @@ public class LazyMetadataValue extends MetadataValueAdapter implements MetadataV NEVER_CACHE, /** - * Once the metadata value has been evaluated, do not re-evaluate the value in spite of manual invalidation. + * Once the metadata value has been evaluated, do not re-evaluate the + * value in spite of manual invalidation. */ CACHE_ETERNALLY } diff --git a/src/main/java/org/bukkit/metadata/MetadataConversionException.java b/src/main/java/org/bukkit/metadata/MetadataConversionException.java index ff4d1205..a3def46a 100644 --- a/src/main/java/org/bukkit/metadata/MetadataConversionException.java +++ b/src/main/java/org/bukkit/metadata/MetadataConversionException.java @@ -1,10 +1,10 @@ package org.bukkit.metadata; /** - * A MetadataConversionException is thrown any time a {@link LazyMetadataValue} attempts to convert a metadata value - * to an inappropriate data type. + * A MetadataConversionException is thrown any time a {@link + * LazyMetadataValue} attempts to convert a metadata value to an inappropriate + * data type. */ - @SuppressWarnings("serial") public class MetadataConversionException extends RuntimeException { MetadataConversionException(String message) { diff --git a/src/main/java/org/bukkit/metadata/MetadataEvaluationException.java b/src/main/java/org/bukkit/metadata/MetadataEvaluationException.java index 6b5ac886..918e7c83 100644 --- a/src/main/java/org/bukkit/metadata/MetadataEvaluationException.java +++ b/src/main/java/org/bukkit/metadata/MetadataEvaluationException.java @@ -1,10 +1,10 @@ package org.bukkit.metadata; /** - * A MetadataEvaluationException is thrown any time a {@link LazyMetadataValue} fails to evaluate its value due to - * an exception. The originating exception will be included as this exception's cause. + * A MetadataEvaluationException is thrown any time a {@link + * LazyMetadataValue} fails to evaluate its value due to an exception. The + * originating exception will be included as this exception's cause. */ - @SuppressWarnings("serial") public class MetadataEvaluationException extends RuntimeException { MetadataEvaluationException(Throwable cause) { diff --git a/src/main/java/org/bukkit/metadata/MetadataStore.java b/src/main/java/org/bukkit/metadata/MetadataStore.java index 273a273f..700d0bfb 100644 --- a/src/main/java/org/bukkit/metadata/MetadataStore.java +++ b/src/main/java/org/bukkit/metadata/MetadataStore.java @@ -11,24 +11,27 @@ public interface MetadataStore<T> { * @param subject The object receiving the metadata. * @param metadataKey A unique key to identify this metadata. * @param newMetadataValue The metadata value to apply. - * @throws IllegalArgumentException If value is null, or the owning plugin is null + * @throws IllegalArgumentException If value is null, or the owning plugin + * is null */ public void setMetadata(T subject, String metadataKey, MetadataValue newMetadataValue); /** - * Returns all metadata values attached to an object. If multiple plugins have attached metadata, each will value - * will be included. + * Returns all metadata values attached to an object. If multiple plugins + * have attached metadata, each will value will be included. * * @param subject the object being interrogated. * @param metadataKey the unique metadata key being sought. - * @return A list of values, one for each plugin that has set the requested value. + * @return A list of values, one for each plugin that has set the + * requested value. */ public List<MetadataValue> getMetadata(T subject, String metadataKey); /** * Tests to see if a metadata attribute has been set on an object. * - * @param subject the object upon which the has-metadata test is performed. + * @param subject the object upon which the has-metadata test is + * performed. * @param metadataKey the unique metadata key being queried. * @return the existence of the metadataKey within subject. */ @@ -38,15 +41,17 @@ public interface MetadataStore<T> { * Removes a metadata item owned by a plugin from a subject. * * @param subject the object to remove the metadata from. - * @param metadataKey the unique metadata key identifying the metadata to remove. + * @param metadataKey the unique metadata key identifying the metadata to + * remove. * @param owningPlugin the plugin attempting to remove a metadata item. * @throws IllegalArgumentException If plugin is null */ public void removeMetadata(T subject, String metadataKey, Plugin owningPlugin); /** - * Invalidates all metadata in the metadata store that originates from the given plugin. Doing this will force - * each invalidated metadata item to be recalculated the next time it is accessed. + * Invalidates all metadata in the metadata store that originates from the + * given plugin. Doing this will force each invalidated metadata item to + * be recalculated the next time it is accessed. * * @param owningPlugin the plugin requesting the invalidation. * @throws IllegalArgumentException If plugin is null diff --git a/src/main/java/org/bukkit/metadata/MetadataStoreBase.java b/src/main/java/org/bukkit/metadata/MetadataStoreBase.java index 28f35fd1..093c1445 100644 --- a/src/main/java/org/bukkit/metadata/MetadataStoreBase.java +++ b/src/main/java/org/bukkit/metadata/MetadataStoreBase.java @@ -9,20 +9,26 @@ public abstract class MetadataStoreBase<T> { private Map<String, Map<Plugin, MetadataValue>> metadataMap = new HashMap<String, Map<Plugin, MetadataValue>>(); /** - * Adds a metadata value to an object. Each metadata value is owned by a specific{@link Plugin}. - * If a plugin has already added a metadata value to an object, that value - * will be replaced with the value of {@code newMetadataValue}. Multiple plugins can set independent values for - * the same {@code metadataKey} without conflict. - * <p/> - * Implementation note: I considered using a {@link java.util.concurrent.locks.ReadWriteLock} for controlling - * access to {@code metadataMap}, but decided that the added overhead wasn't worth the finer grained access control. - * Bukkit is almost entirely single threaded so locking overhead shouldn't pose a problem. + * Adds a metadata value to an object. Each metadata value is owned by a + * specific {@link Plugin}. If a plugin has already added a metadata value + * to an object, that value will be replaced with the value of {@code + * newMetadataValue}. Multiple plugins can set independent values for the + * same {@code metadataKey} without conflict. + * <p> + * Implementation note: I considered using a {@link + * java.util.concurrent.locks.ReadWriteLock} for controlling access to + * {@code metadataMap}, but decided that the added overhead wasn't worth + * the finer grained access control. + * <p> + * Bukkit is almost entirely single threaded so locking overhead shouldn't + * pose a problem. * - * @param subject The object receiving the metadata. - * @param metadataKey A unique key to identify this metadata. + * @param subject The object receiving the metadata. + * @param metadataKey A unique key to identify this metadata. * @param newMetadataValue The metadata value to apply. * @see MetadataStore#setMetadata(Object, String, MetadataValue) - * @throws IllegalArgumentException If value is null, or the owning plugin is null + * @throws IllegalArgumentException If value is null, or the owning plugin + * is null */ public synchronized void setMetadata(T subject, String metadataKey, MetadataValue newMetadataValue) { Validate.notNull(newMetadataValue, "Value cannot be null"); @@ -38,12 +44,13 @@ public abstract class MetadataStoreBase<T> { } /** - * Returns all metadata values attached to an object. If multiple plugins have attached metadata, each will value - * will be included. + * Returns all metadata values attached to an object. If multiple + * have attached metadata, each will value will be included. * - * @param subject the object being interrogated. + * @param subject the object being interrogated. * @param metadataKey the unique metadata key being sought. - * @return A list of values, one for each plugin that has set the requested value. + * @return A list of values, one for each plugin that has set the + * requested value. * @see MetadataStore#getMetadata(Object, String) */ public synchronized List<MetadataValue> getMetadata(T subject, String metadataKey) { @@ -59,7 +66,8 @@ public abstract class MetadataStoreBase<T> { /** * Tests to see if a metadata attribute has been set on an object. * - * @param subject the object upon which the has-metadata test is performed. + * @param subject the object upon which the has-metadata test is + * performed. * @param metadataKey the unique metadata key being queried. * @return the existence of the metadataKey within subject. */ @@ -71,10 +79,12 @@ public abstract class MetadataStoreBase<T> { /** * Removes a metadata item owned by a plugin from a subject. * - * @param subject the object to remove the metadata from. - * @param metadataKey the unique metadata key identifying the metadata to remove. + * @param subject the object to remove the metadata from. + * @param metadataKey the unique metadata key identifying the metadata to + * remove. * @param owningPlugin the plugin attempting to remove a metadata item. - * @see MetadataStore#removeMetadata(Object, String, org.bukkit.plugin.Plugin) + * @see MetadataStore#removeMetadata(Object, String, + * org.bukkit.plugin.Plugin) * @throws IllegalArgumentException If plugin is null */ public synchronized void removeMetadata(T subject, String metadataKey, Plugin owningPlugin) { @@ -92,8 +102,9 @@ public abstract class MetadataStoreBase<T> { } /** - * Invalidates all metadata in the metadata store that originates from the given plugin. Doing this will force - * each invalidated metadata item to be recalculated the next time it is accessed. + * Invalidates all metadata in the metadata store that originates from the + * given plugin. Doing this will force each invalidated metadata item to + * be recalculated the next time it is accessed. * * @param owningPlugin the plugin requesting the invalidation. * @see MetadataStore#invalidateAll(org.bukkit.plugin.Plugin) @@ -109,12 +120,15 @@ public abstract class MetadataStoreBase<T> { } /** - * Creates a unique name for the object receiving metadata by combining unique data from the subject with a metadataKey. - * The name created must be globally unique for the given object and any two equivalent objects must generate the - * same unique name. For example, two Player objects must generate the same string if they represent the same player, - * even if the objects would fail a reference equality test. + * Creates a unique name for the object receiving metadata by combining + * unique data from the subject with a metadataKey. + * <p> + * The name created must be globally unique for the given object and any + * two equivalent objects must generate the same unique name. For example, + * two Player objects must generate the same string if they represent the + * same player, even if the objects would fail a reference equality test. * - * @param subject The object for which this key is being generated. + * @param subject The object for which this key is being generated. * @param metadataKey The name identifying the metadata value. * @return a unique metadata key for the given subject. */ diff --git a/src/main/java/org/bukkit/metadata/MetadataValue.java b/src/main/java/org/bukkit/metadata/MetadataValue.java index 1a7f0a46..eded8c04 100644 --- a/src/main/java/org/bukkit/metadata/MetadataValue.java +++ b/src/main/java/org/bukkit/metadata/MetadataValue.java @@ -70,12 +70,14 @@ public interface MetadataValue { /** * Returns the {@link Plugin} that created this metadata item. * - * @return the plugin that owns this metadata value. This should never be null. + * @return the plugin that owns this metadata value. This should never be + * null. */ public Plugin getOwningPlugin(); /** - * Invalidates this metadata item, forcing it to recompute when next accessed. + * Invalidates this metadata item, forcing it to recompute when next + * accessed. */ public void invalidate(); } diff --git a/src/main/java/org/bukkit/metadata/MetadataValueAdapter.java b/src/main/java/org/bukkit/metadata/MetadataValueAdapter.java index 48a7b6e4..bbc3da86 100644 --- a/src/main/java/org/bukkit/metadata/MetadataValueAdapter.java +++ b/src/main/java/org/bukkit/metadata/MetadataValueAdapter.java @@ -9,9 +9,9 @@ import org.bukkit.util.NumberConversions; /** * Optional base class for facilitating MetadataValue implementations. * <p> - * This provides all the conversion functions for MetadataValue - * so that writing an implementation of MetadataValue is as simple - * as implementing value() and invalidate(). + * This provides all the conversion functions for MetadataValue so that + * writing an implementation of MetadataValue is as simple as implementing + * value() and invalidate(). */ public abstract class MetadataValueAdapter implements MetadataValue { protected final WeakReference<Plugin> owningPlugin; diff --git a/src/main/java/org/bukkit/metadata/Metadatable.java b/src/main/java/org/bukkit/metadata/Metadatable.java index 41711be8..b47cf2b0 100644 --- a/src/main/java/org/bukkit/metadata/Metadatable.java +++ b/src/main/java/org/bukkit/metadata/Metadatable.java @@ -5,7 +5,8 @@ import org.bukkit.plugin.Plugin; import java.util.List; /** - * This interface is implemented by all objects that can provide metadata about themselves. + * This interface is implemented by all objects that can provide metadata + * about themselves. */ public interface Metadatable { /** @@ -13,20 +14,24 @@ public interface Metadatable { * * @param metadataKey A unique key to identify this metadata. * @param newMetadataValue The metadata value to apply. - * @throws IllegalArgumentException If value is null, or the owning plugin is null + * @throws IllegalArgumentException If value is null, or the owning plugin + * is null */ public void setMetadata(String metadataKey, MetadataValue newMetadataValue); /** - * Returns a list of previously set metadata values from the implementing object's metadata store. + * Returns a list of previously set metadata values from the implementing + * object's metadata store. * * @param metadataKey the unique metadata key being sought. - * @return A list of values, one for each plugin that has set the requested value. + * @return A list of values, one for each plugin that has set the + * requested value. */ public List<MetadataValue> getMetadata(String metadataKey); /** - * Tests to see whether the implementing object contains the given metadata value in its metadata store. + * Tests to see whether the implementing object contains the given + * metadata value in its metadata store. * * @param metadataKey the unique metadata key being queried. * @return the existence of the metadataKey within subject. @@ -34,10 +39,13 @@ public interface Metadatable { public boolean hasMetadata(String metadataKey); /** - * Removes the given metadata value from the implementing object's metadata store. + * Removes the given metadata value from the implementing object's + * metadata store. * - * @param metadataKey the unique metadata key identifying the metadata to remove. - * @param owningPlugin This plugin's metadata value will be removed. All other values will be left untouched. + * @param metadataKey the unique metadata key identifying the metadata to + * remove. + * @param owningPlugin This plugin's metadata value will be removed. All + * other values will be left untouched. * @throws IllegalArgumentException If plugin is null */ public void removeMetadata(String metadataKey, Plugin owningPlugin); diff --git a/src/main/java/org/bukkit/permissions/Permissible.java b/src/main/java/org/bukkit/permissions/Permissible.java index 66a0c810..5cd3cff0 100644 --- a/src/main/java/org/bukkit/permissions/Permissible.java +++ b/src/main/java/org/bukkit/permissions/Permissible.java @@ -9,7 +9,8 @@ import org.bukkit.plugin.Plugin; public interface Permissible extends ServerOperator { /** - * Checks if this object contains an override for the specified permission, by fully qualified name + * Checks if this object contains an override for the specified + * permission, by fully qualified name * * @param name Name of the permission * @return true if the permission is set, otherwise false @@ -17,7 +18,8 @@ public interface Permissible extends ServerOperator { public boolean isPermissionSet(String name); /** - * Checks if this object contains an override for the specified {@link Permission} + * Checks if this object contains an override for the specified {@link + * Permission} * * @param perm Permission to check * @return true if the permission is set, otherwise false @@ -27,7 +29,8 @@ public interface Permissible extends ServerOperator { /** * Gets the value of the specified permission, if set. * <p> - * If a permission override is not set on this object, the default value of the permission will be returned. + * If a permission override is not set on this object, the default value + * of the permission will be returned. * * @param name Name of the permission * @return Value of the permission @@ -37,7 +40,8 @@ public interface Permissible extends ServerOperator { /** * Gets the value of the specified permission, if set. * <p> - * If a permission override is not set on this object, the default value of the permission will be returned + * If a permission override is not set on this object, the default value + * of the permission will be returned * * @param perm Permission to get * @return Value of the permission @@ -45,9 +49,11 @@ public interface Permissible extends ServerOperator { public boolean hasPermission(Permission perm); /** - * Adds a new {@link PermissionAttachment} with a single permission by name and value + * Adds a new {@link PermissionAttachment} with a single permission by + * name and value * - * @param plugin Plugin responsible for this attachment, may not be null or disabled + * @param plugin Plugin responsible for this attachment, may not be null + * or disabled * @param name Name of the permission to attach * @param value Value of the permission * @return The PermissionAttachment that was just created @@ -57,27 +63,34 @@ public interface Permissible extends ServerOperator { /** * Adds a new empty {@link PermissionAttachment} to this object * - * @param plugin Plugin responsible for this attachment, may not be null or disabled + * @param plugin Plugin responsible for this attachment, may not be null + * or disabled * @return The PermissionAttachment that was just created */ public PermissionAttachment addAttachment(Plugin plugin); /** - * Temporarily adds a new {@link PermissionAttachment} with a single permission by name and value + * Temporarily adds a new {@link PermissionAttachment} with a single + * permission by name and value * - * @param plugin Plugin responsible for this attachment, may not be null or disabled + * @param plugin Plugin responsible for this attachment, may not be null + * or disabled * @param name Name of the permission to attach * @param value Value of the permission - * @param ticks Amount of ticks to automatically remove this attachment after + * @param ticks Amount of ticks to automatically remove this attachment + * after * @return The PermissionAttachment that was just created */ public PermissionAttachment addAttachment(Plugin plugin, String name, boolean value, int ticks); /** - * Temporarily adds a new empty {@link PermissionAttachment} to this object + * Temporarily adds a new empty {@link PermissionAttachment} to this + * object * - * @param plugin Plugin responsible for this attachment, may not be null or disabled - * @param ticks Amount of ticks to automatically remove this attachment after + * @param plugin Plugin responsible for this attachment, may not be null + * or disabled + * @param ticks Amount of ticks to automatically remove this attachment + * after * @return The PermissionAttachment that was just created */ public PermissionAttachment addAttachment(Plugin plugin, int ticks); @@ -86,19 +99,22 @@ public interface Permissible extends ServerOperator { * Removes the given {@link PermissionAttachment} from this object * * @param attachment Attachment to remove - * @throws IllegalArgumentException Thrown when the specified attachment isn't part of this object + * @throws IllegalArgumentException Thrown when the specified attachment + * isn't part of this object */ public void removeAttachment(PermissionAttachment attachment); /** - * Recalculates the permissions for this object, if the attachments have changed values. + * Recalculates the permissions for this object, if the attachments have + * changed values. * <p> * This should very rarely need to be called from a plugin. */ public void recalculatePermissions(); /** - * Gets a set containing all of the permissions currently in effect by this object + * Gets a set containing all of the permissions currently in effect by + * this object * * @return Set of currently effective permissions */ diff --git a/src/main/java/org/bukkit/permissions/Permission.java b/src/main/java/org/bukkit/permissions/Permission.java index 190c3c04..26f6f2bb 100644 --- a/src/main/java/org/bukkit/permissions/Permission.java +++ b/src/main/java/org/bukkit/permissions/Permission.java @@ -12,7 +12,8 @@ import org.bukkit.Bukkit; import org.bukkit.plugin.PluginManager; /** - * Represents a unique permission that may be attached to a {@link Permissible} + * Represents a unique permission that may be attached to a {@link + * Permissible} */ public class Permission { public static final PermissionDefault DEFAULT_PERMISSION = PermissionDefault.OP; @@ -77,7 +78,8 @@ public class Permission { /** * Gets the children of this permission. * <p> - * If you change this map in any form, you must call {@link #recalculatePermissibles()} to recalculate all {@link Permissible}s + * If you change this map in any form, you must call {@link + * #recalculatePermissibles()} to recalculate all {@link Permissible}s * * @return Permission children */ @@ -97,8 +99,10 @@ public class Permission { /** * Sets the default value of this permission. * <p> - * This will not be saved to disk, and is a temporary operation until the server reloads permissions. - * Changing this default will cause all {@link Permissible}s that contain this permission to recalculate their permissions + * This will not be saved to disk, and is a temporary operation until the + * server reloads permissions. Changing this default will cause all {@link + * Permissible}s that contain this permission to recalculate their + * permissions * * @param value The new default to set */ @@ -123,7 +127,8 @@ public class Permission { /** * Sets the description of this permission. * <p> - * This will not be saved to disk, and is a temporary operation until the server reloads permissions. + * This will not be saved to disk, and is a temporary operation until the + * server reloads permissions. * * @param value The new description to set */ @@ -136,7 +141,8 @@ public class Permission { } /** - * Gets a set containing every {@link Permissible} that has this permission. + * Gets a set containing every {@link Permissible} that has this + * permission. * <p> * This set cannot be modified. * @@ -149,7 +155,8 @@ public class Permission { /** * Recalculates all {@link Permissible}s that contain this permission. * <p> - * This should be called after modifying the children, and is automatically called after modifying the default value + * This should be called after modifying the children, and is + * automatically called after modifying the default value */ public void recalculatePermissibles() { Set<Permissible> perms = getPermissibles(); @@ -164,7 +171,8 @@ public class Permission { /** * Adds this permission to the specified parent permission. * <p> - * If the parent permission does not exist, it will be created and registered. + * If the parent permission does not exist, it will be created and + * registered. * * @param name Name of the parent permission * @param value The value to set this permission to @@ -198,12 +206,18 @@ public class Permission { } /** - * Loads a list of Permissions from a map of data, usually used from retrieval from a yaml file. + * Loads a list of Permissions from a map of data, usually used from + * retrieval from a yaml file. * <p> - * The data may contain a list of name:data, where the data contains the following keys: - * default: Boolean true or false. If not specified, false. - * children: Map<String, Boolean> of child permissions. If not specified, empty list. - * description: Short string containing a very small description of this description. If not specified, empty string. + * The data may contain a list of name:data, where the data contains the + * following keys: + * <ul> + * <li>default: Boolean true or false. If not specified, false. + * <li>children: Map<String, Boolean> of child permissions. If not + * specified, empty list. + * <li>description: Short string containing a very small description of + * this description. If not specified, empty string. + * </ul> * * @param data Map of permissions * @param error An error message to show if a permission is invalid. @@ -225,12 +239,16 @@ public class Permission { } /** - * Loads a Permission from a map of data, usually used from retrieval from a yaml file. + * Loads a Permission from a map of data, usually used from retrieval from + * a yaml file. * <p> * The data may contain the following keys: - * default: Boolean true or false. If not specified, false. - * children: Map<String, Boolean> of child permissions. If not specified, empty list. - * description: Short string containing a very small description of this description. If not specified, empty string. + * <ul> + * <li>default: Boolean true or false. If not specified, false. + * <li>children: Map<String, Boolean> of child permissions. If not + * specified, empty list. + * <li>description: Short string containing a very small description of + * this description. If not specified, empty string. * * @param name Name of the permission * @param data Map of keys @@ -241,12 +259,17 @@ public class Permission { } /** - * Loads a Permission from a map of data, usually used from retrieval from a yaml file. + * Loads a Permission from a map of data, usually used from retrieval from + * a yaml file. * <p> * The data may contain the following keys: - * default: Boolean true or false. If not specified, false. - * children: Map<String, Boolean> of child permissions. If not specified, empty list. - * description: Short string containing a very small description of this description. If not specified, empty string. + * <ul> + * <li>default: Boolean true or false. If not specified, false. + * <li>children: Map<String, Boolean> of child permissions. If not + * specified, empty list. + * <li>description: Short string containing a very small description of + * this description. If not specified, empty string. + * </ul> * * @param name Name of the permission * @param data Map of keys diff --git a/src/main/java/org/bukkit/permissions/PermissionAttachment.java b/src/main/java/org/bukkit/permissions/PermissionAttachment.java index f94bc98e..b2a44d51 100644 --- a/src/main/java/org/bukkit/permissions/PermissionAttachment.java +++ b/src/main/java/org/bukkit/permissions/PermissionAttachment.java @@ -5,7 +5,8 @@ import java.util.Map; import org.bukkit.plugin.Plugin; /** - * Holds information about a permission attachment on a {@link Permissible} object + * Holds information about a permission attachment on a {@link Permissible} + * object */ public class PermissionAttachment { private PermissionRemovedExecutor removed; @@ -34,7 +35,8 @@ public class PermissionAttachment { } /** - * Sets an object to be called for when this attachment is removed from a {@link Permissible}. May be null. + * Sets an object to be called for when this attachment is removed from a + * {@link Permissible}. May be null. * * @param ex Object to be called when this is removed */ @@ -43,7 +45,8 @@ public class PermissionAttachment { } /** - * Gets the class that was previously set to be called when this attachment was removed from a {@link Permissible}. May be null. + * Gets the class that was previously set to be called when this + * attachment was removed from a {@link Permissible}. May be null. * * @return Object to be called when this is removed */ @@ -61,9 +64,11 @@ public class PermissionAttachment { } /** - * Gets a copy of all set permissions and values contained within this attachment. + * Gets a copy of all set permissions and values contained within this + * attachment. * <p> - * This map may be modified but will not affect the attachment, as it is a copy. + * This map may be modified but will not affect the attachment, as it is a + * copy. * * @return Copy of all permissions and values expressed by this attachment */ @@ -95,7 +100,8 @@ public class PermissionAttachment { /** * Removes the specified permission from this attachment. * <p> - * If the permission does not exist in this attachment, nothing will happen. + * If the permission does not exist in this attachment, nothing will + * happen. * * @param name Name of the permission to remove */ @@ -107,7 +113,8 @@ public class PermissionAttachment { /** * Removes the specified permission from this attachment. * <p> - * If the permission does not exist in this attachment, nothing will happen. + * If the permission does not exist in this attachment, nothing will + * happen. * * @param perm Permission to remove */ @@ -118,7 +125,8 @@ public class PermissionAttachment { /** * Removes this attachment from its registered {@link Permissible} * - * @return true if the permissible was removed successfully, false if it did not exist + * @return true if the permissible was removed successfully, false if it + * did not exist */ public boolean remove() { try { diff --git a/src/main/java/org/bukkit/permissions/PermissionAttachmentInfo.java b/src/main/java/org/bukkit/permissions/PermissionAttachmentInfo.java index 77f49172..8e8e3355 100644 --- a/src/main/java/org/bukkit/permissions/PermissionAttachmentInfo.java +++ b/src/main/java/org/bukkit/permissions/PermissionAttachmentInfo.java @@ -1,7 +1,8 @@ package org.bukkit.permissions; /** - * Holds information on a permission and which {@link PermissionAttachment} provides it + * Holds information on a permission and which {@link PermissionAttachment} + * provides it */ public class PermissionAttachmentInfo { private final Permissible permissible; @@ -41,8 +42,8 @@ public class PermissionAttachmentInfo { } /** - * Gets the attachment providing this permission. This may be null for default - * permissions (usually parent permissions). + * Gets the attachment providing this permission. This may be null for + * default permissions (usually parent permissions). * * @return Attachment */ diff --git a/src/main/java/org/bukkit/permissions/PermissionDefault.java b/src/main/java/org/bukkit/permissions/PermissionDefault.java index eb507c4c..045e733b 100644 --- a/src/main/java/org/bukkit/permissions/PermissionDefault.java +++ b/src/main/java/org/bukkit/permissions/PermissionDefault.java @@ -20,7 +20,8 @@ public enum PermissionDefault { } /** - * Calculates the value of this PermissionDefault for the given operator value + * Calculates the value of this PermissionDefault for the given operator + * value * * @param op If the target is op * @return True if the default should be true, or false diff --git a/src/main/java/org/bukkit/permissions/PermissionRemovedExecutor.java b/src/main/java/org/bukkit/permissions/PermissionRemovedExecutor.java index aa797eec..b13d0082 100644 --- a/src/main/java/org/bukkit/permissions/PermissionRemovedExecutor.java +++ b/src/main/java/org/bukkit/permissions/PermissionRemovedExecutor.java @@ -1,12 +1,14 @@ package org.bukkit.permissions; /** - * Represents a class which is to be notified when a {@link PermissionAttachment} is removed from a {@link Permissible} + * 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} + * Called when a {@link PermissionAttachment} is removed from a {@link + * Permissible} * * @param attachment Attachment which was removed */ diff --git a/src/main/java/org/bukkit/permissions/ServerOperator.java b/src/main/java/org/bukkit/permissions/ServerOperator.java index e4faa87f..26ed2430 100644 --- a/src/main/java/org/bukkit/permissions/ServerOperator.java +++ b/src/main/java/org/bukkit/permissions/ServerOperator.java @@ -3,7 +3,8 @@ package org.bukkit.permissions; import org.bukkit.entity.Player; /** - * Represents an object that may become a server operator, such as a {@link Player} + * Represents an object that may become a server operator, such as a {@link + * Player} */ public interface ServerOperator { diff --git a/src/main/java/org/bukkit/plugin/IllegalPluginAccessException.java b/src/main/java/org/bukkit/plugin/IllegalPluginAccessException.java index 4e60e208..b25447dc 100644 --- a/src/main/java/org/bukkit/plugin/IllegalPluginAccessException.java +++ b/src/main/java/org/bukkit/plugin/IllegalPluginAccessException.java @@ -1,18 +1,21 @@ package org.bukkit.plugin; /** - * Thrown when a plugin attempts to interact with the server when it is not enabled + * Thrown when a plugin attempts to interact with the server when it is not + * enabled */ @SuppressWarnings("serial") public class IllegalPluginAccessException extends RuntimeException { /** - * Creates a new instance of <code>IllegalPluginAccessException</code> without detail message. + * Creates a new instance of <code>IllegalPluginAccessException</code> + * without detail message. */ public IllegalPluginAccessException() {} /** - * Constructs an instance of <code>IllegalPluginAccessException</code> with the specified detail message. + * Constructs an instance of <code>IllegalPluginAccessException</code> + * with the specified detail message. * * @param msg the detail message. */ diff --git a/src/main/java/org/bukkit/plugin/InvalidDescriptionException.java b/src/main/java/org/bukkit/plugin/InvalidDescriptionException.java index a8c0bf86..0a77c2e2 100644 --- a/src/main/java/org/bukkit/plugin/InvalidDescriptionException.java +++ b/src/main/java/org/bukkit/plugin/InvalidDescriptionException.java @@ -7,7 +7,8 @@ public class InvalidDescriptionException extends Exception { private static final long serialVersionUID = 5721389122281775896L; /** - * Constructs a new InvalidDescriptionException based on the given Exception + * Constructs a new InvalidDescriptionException based on the given + * Exception * * @param message Brief message explaining the cause of the exception * @param cause Exception that triggered this Exception @@ -17,7 +18,8 @@ public class InvalidDescriptionException extends Exception { } /** - * Constructs a new InvalidDescriptionException based on the given Exception + * Constructs a new InvalidDescriptionException based on the given + * Exception * * @param cause Exception that triggered this Exception */ diff --git a/src/main/java/org/bukkit/plugin/InvalidPluginException.java b/src/main/java/org/bukkit/plugin/InvalidPluginException.java index 1556ba52..7ddf7b62 100644 --- a/src/main/java/org/bukkit/plugin/InvalidPluginException.java +++ b/src/main/java/org/bukkit/plugin/InvalidPluginException.java @@ -23,19 +23,25 @@ public class InvalidPluginException extends Exception { } /** - * Constructs a new InvalidPluginException with the specified detail message and cause. + * Constructs a new InvalidPluginException with the specified detail + * message and cause. * - * @param message the detail message (which is saved for later retrieval by the getMessage() method). - * @param cause the cause (which is saved for later retrieval by the getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.) + * @param message the detail message (which is saved for later retrieval + * by the getMessage() method). + * @param cause the cause (which is saved for later retrieval by the + * getCause() method). (A null value is permitted, and indicates that + * the cause is nonexistent or unknown.) */ public InvalidPluginException(final String message, final Throwable cause) { super(message, cause); } /** - * Constructs a new InvalidPluginException with the specified detail message + * Constructs a new InvalidPluginException with the specified detail + * message * - * @param message TThe 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/Plugin.java b/src/main/java/org/bukkit/plugin/Plugin.java index 1e95d03c..af58c9de 100644 --- a/src/main/java/org/bukkit/plugin/Plugin.java +++ b/src/main/java/org/bukkit/plugin/Plugin.java @@ -33,10 +33,11 @@ public interface Plugin extends TabExecutor { public PluginDescriptionFile getDescription(); /** - * Gets a {@link FileConfiguration} for this plugin, read through "config.yml" + * Gets a {@link FileConfiguration} for this plugin, read through + * "config.yml" * <p> - * If there is a default config.yml embedded in this plugin, it will be provided - * as a default for this Configuration. + * If there is a default config.yml embedded in this plugin, it will be + * provided as a default for this Configuration. * * @return Plugin configuration */ @@ -56,20 +57,26 @@ public interface Plugin extends TabExecutor { public void saveConfig(); /** - * Saves the raw contents of the default config.yml file to the location retrievable by {@link #getConfig()}. - * If there is no default config.yml embedded in the plugin, an empty config.yml file is saved. - * This should fail silently if the config.yml already exists. + * Saves the raw contents of the default config.yml file to the location + * retrievable by {@link #getConfig()}. If there is no default config.yml + * embedded in the plugin, an empty config.yml file is saved. This should + * fail silently if the config.yml already exists. */ public void saveDefaultConfig(); /** - * Saves the raw contents of any resource embedded with a plugin's .jar file assuming it can be found using - * {@link #getResource(String)}. The resource is saved into the plugin's data folder using the same hierarchy - * as the .jar file (subdirectories are preserved). + * Saves the raw contents of any resource embedded with a plugin's .jar + * file assuming it can be found using {@link #getResource(String)}. + * <p> + * The resource is saved into the plugin's data folder using the same + * hierarchy as the .jar file (subdirectories are preserved). * - * @param resourcePath the embedded resource path to look for within the plugin's .jar file. (No preceding slash). - * @param replace if true, the embedded resource will overwrite the contents of an existing file. - * @throws IllegalArgumentException if the resource path is null, empty, or points to a nonexistent resource. + * @param resourcePath the embedded resource path to look for within the + * plugin's .jar file. (No preceding slash). + * @param replace if true, the embedded resource will overwrite the + * contents of an existing file. + * @throws IllegalArgumentException if the resource path is null, empty, + * or points to a nonexistent resource. */ public void saveResource(String resourcePath, boolean replace); @@ -93,7 +100,8 @@ public interface Plugin extends TabExecutor { public Server getServer(); /** - * Returns a value indicating whether or not this plugin is currently enabled + * Returns a value indicating whether or not this plugin is currently + * enabled * * @return true if this plugin is enabled, otherwise false */ @@ -106,7 +114,9 @@ public interface Plugin extends TabExecutor { /** * Called after a plugin is loaded but before it has been enabled. - * When mulitple plugins are loaded, the onLoad() for all plugins is called before any onEnable() is called. + * <p> + * When mulitple plugins are loaded, the onLoad() for all plugins is + * called before any onEnable() is called. */ public void onLoad(); @@ -148,17 +158,20 @@ public interface Plugin extends TabExecutor { public EbeanServer getDatabase(); /** - * Gets a {@link ChunkGenerator} for use in a default world, as specified in the server configuration + * Gets a {@link ChunkGenerator} for use in a default world, as specified + * in the server configuration * * @param worldName Name of the world that this will be applied to - * @param id Unique ID, if any, that was specified to indicate which generator was requested + * @param id Unique ID, if any, that was specified to indicate which + * generator was requested * @return ChunkGenerator for use in the default world generation */ public ChunkGenerator getDefaultWorldGenerator(String worldName, String id); /** - * Returns the primary logger associated with this server instance. The returned logger automatically - * tags all log messages with the plugin's name. + * Returns the primary logger associated with this server instance. The + * returned logger automatically tags all log messages with the plugin's + * name. * * @return Logger associated with this server */ @@ -167,7 +180,8 @@ public interface Plugin extends TabExecutor { /** * Returns the name of the plugin. * <p> - * This should return the bare name of the plugin and should be used for comparison. + * This should return the bare name of the plugin and should be used for + * comparison. * * @return name of the plugin */ diff --git a/src/main/java/org/bukkit/plugin/PluginBase.java b/src/main/java/org/bukkit/plugin/PluginBase.java index 8d5f37d3..6031af11 100644 --- a/src/main/java/org/bukkit/plugin/PluginBase.java +++ b/src/main/java/org/bukkit/plugin/PluginBase.java @@ -3,7 +3,8 @@ package org.bukkit.plugin; /** * Represents a base {@link Plugin} * <p> - * Extend this class if your plugin is not a {@link org.bukkit.plugin.java.JavaPlugin} + * Extend this class if your plugin is not a {@link + * org.bukkit.plugin.java.JavaPlugin} */ public abstract class PluginBase implements Plugin { @Override diff --git a/src/main/java/org/bukkit/plugin/PluginLoadOrder.java b/src/main/java/org/bukkit/plugin/PluginLoadOrder.java index bd647230..b77436fd 100644 --- a/src/main/java/org/bukkit/plugin/PluginLoadOrder.java +++ b/src/main/java/org/bukkit/plugin/PluginLoadOrder.java @@ -4,12 +4,14 @@ package org.bukkit.plugin; * Represents the order in which a plugin should be initialized and enabled */ public enum PluginLoadOrder { + /** * Indicates that the plugin will be loaded at startup */ STARTUP, /** - * Indicates that the plugin will be loaded after the first/default world was created + * Indicates that the plugin will be loaded after the first/default world + * was created */ POSTWORLD } diff --git a/src/main/java/org/bukkit/plugin/PluginLoader.java b/src/main/java/org/bukkit/plugin/PluginLoader.java index 950c9fcc..e7981a1d 100644 --- a/src/main/java/org/bukkit/plugin/PluginLoader.java +++ b/src/main/java/org/bukkit/plugin/PluginLoader.java @@ -19,9 +19,11 @@ public interface PluginLoader { * * @param file File to attempt to load * @return Plugin that was contained in the specified file, or null if - * unsuccessful - * @throws InvalidPluginException Thrown when the specified file is not a plugin - * @throws UnknownDependencyException If a required dependency could not be found + * unsuccessful + * @throws InvalidPluginException Thrown when the specified file is not a + * plugin + * @throws UnknownDependencyException If a required dependency could not + * be found */ public Plugin loadPlugin(File file) throws InvalidPluginException, UnknownDependencyException; @@ -29,8 +31,10 @@ public interface PluginLoader { * Loads a PluginDescriptionFile from the specified file * * @param file File to attempt to load from - * @return A new PluginDescriptionFile loaded from the plugin.yml in the specified file - * @throws InvalidDescriptionException If the plugin description file could not be created + * @return A new PluginDescriptionFile loaded from the plugin.yml in the + * specified file + * @throws InvalidDescriptionException If the plugin description file + * could not be created */ public PluginDescriptionFile getPluginDescription(File file) throws InvalidDescriptionException; @@ -42,7 +46,8 @@ public interface PluginLoader { public Pattern[] getPluginFileFilters(); /** - * Creates and returns registered listeners for the event classes used in this listener + * Creates and returns registered listeners for the event classes used in + * this listener * * @param listener The object that will handle the eventual call back * @param plugin The plugin to use when creating registered listeners @@ -53,7 +58,8 @@ public interface PluginLoader { /** * Enables the specified plugin * <p> - * Attempting to enable a plugin that is already enabled will have no effect + * Attempting to enable a plugin that is already enabled will have no + * effect * * @param plugin Plugin to enable */ diff --git a/src/main/java/org/bukkit/plugin/PluginLogger.java b/src/main/java/org/bukkit/plugin/PluginLogger.java index 3d917e4b..f43c10b0 100644 --- a/src/main/java/org/bukkit/plugin/PluginLogger.java +++ b/src/main/java/org/bukkit/plugin/PluginLogger.java @@ -5,8 +5,9 @@ import java.util.logging.LogRecord; import java.util.logging.Logger; /** - * 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 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}. * * @see Logger */ diff --git a/src/main/java/org/bukkit/plugin/PluginManager.java b/src/main/java/org/bukkit/plugin/PluginManager.java index cde9c36f..e5638d56 100644 --- a/src/main/java/org/bukkit/plugin/PluginManager.java +++ b/src/main/java/org/bukkit/plugin/PluginManager.java @@ -18,7 +18,8 @@ public interface PluginManager { * Registers the specified plugin loader * * @param loader Class name of the PluginLoader to register - * @throws IllegalArgumentException Thrown when the given Class is not a valid PluginLoader + * @throws IllegalArgumentException Thrown when the given Class is not a + * valid PluginLoader */ public void registerInterface(Class<? extends PluginLoader> loader) throws IllegalArgumentException; @@ -64,9 +65,12 @@ public interface PluginManager { * * @param file File containing the plugin to load * @return The Plugin loaded, or null if it was invalid - * @throws InvalidPluginException Thrown when the specified file is not a valid plugin - * @throws InvalidDescriptionException Thrown when the specified file contains an invalid description - * @throws UnknownDependencyException If a required dependency could not be resolved + * @throws InvalidPluginException Thrown when the specified file is not a + * valid plugin + * @throws InvalidDescriptionException Thrown when the specified file + * contains an invalid description + * @throws UnknownDependencyException If a required dependency could not + * be resolved */ public Plugin loadPlugin(File file) throws InvalidPluginException, InvalidDescriptionException, UnknownDependencyException; @@ -92,9 +96,11 @@ public interface PluginManager { * Calls an event with the given details * * @param event Event details - * @throws IllegalStateException Thrown when an asynchronous event is fired from synchronous code.<br> - * <i>Note: This is best-effort basis, and should not be used to test synchronized state. This - * is an indicator for flawed flow logic.</i> + * @throws IllegalStateException Thrown when an asynchronous event is + * fired from synchronous code. + * <p> + * <i>Note: This is best-effort basis, and should not be used to test + * synchronized state. This is an indicator for flawed flow logic.</i> */ public void callEvent(Event event) throws IllegalStateException; @@ -132,7 +138,8 @@ public interface PluginManager { /** * Enables the specified plugin * <p> - * Attempting to enable a plugin that is already enabled will have no effect + * Attempting to enable a plugin that is already enabled will have no + * effect * * @param plugin Plugin to enable */ @@ -158,20 +165,23 @@ public interface PluginManager { /** * Adds a {@link Permission} to this plugin manager. * <p> - * If a permission is already defined with the given name of the new permission, - * an exception will be thrown. + * If a permission is already defined with the given name of the new + * permission, an exception will be thrown. * * @param perm Permission to add - * @throws IllegalArgumentException Thrown when a permission with the same name already exists + * @throws IllegalArgumentException Thrown when a permission with the same + * name already exists */ public void addPermission(Permission perm); /** * Removes a {@link Permission} registration from this plugin manager. * <p> - * If the specified permission does not exist in this plugin manager, nothing will happen. + * If the specified permission does not exist in this plugin manager, + * nothing will happen. * <p> - * Removing a permission registration will <b>not</b> remove the permission from any {@link Permissible}s that have it. + * Removing a permission registration will <b>not</b> remove the + * permission from any {@link Permissible}s that have it. * * @param perm Permission to remove */ @@ -180,9 +190,11 @@ public interface PluginManager { /** * Removes a {@link Permission} registration from this plugin manager. * <p> - * If the specified permission does not exist in this plugin manager, nothing will happen. + * If the specified permission does not exist in this plugin manager, + * nothing will happen. * <p> - * Removing a permission registration will <b>not</b> remove the permission from any {@link Permissible}s that have it. + * Removing a permission registration will <b>not</b> remove the + * permission from any {@link Permissible}s that have it. * * @param name Permission to remove */ @@ -199,16 +211,19 @@ public interface PluginManager { /** * Recalculates the defaults for the given {@link Permission}. * <p> - * This will have no effect if the specified permission is not registered here. + * This will have no effect if the specified permission is not registered + * here. * * @param perm Permission to recalculate */ public void recalculatePermissionDefaults(Permission perm); /** - * Subscribes the given Permissible for information about the requested Permission, by name. + * Subscribes the given Permissible for information about the requested + * Permission, by name. * <p> - * If the specified Permission changes in any form, the Permissible will be asked to recalculate. + * If the specified Permission changes in any form, the Permissible will + * be asked to recalculate. * * @param permission Permission to subscribe to * @param permissible Permissible subscribing @@ -216,7 +231,8 @@ public interface PluginManager { public void subscribeToPermission(String permission, Permissible permissible); /** - * Unsubscribes the given Permissible for information about the requested Permission, by name. + * Unsubscribes the given Permissible for information about the requested + * Permission, by name. * * @param permission Permission to unsubscribe from * @param permissible Permissible subscribing @@ -224,7 +240,8 @@ public interface PluginManager { public void unsubscribeFromPermission(String permission, Permissible permissible); /** - * Gets a set containing all subscribed {@link Permissible}s to the given permission, by name + * Gets a set containing all subscribed {@link Permissible}s to the given + * permission, by name * * @param permission Permission to query for * @return Set containing all subscribed permissions @@ -234,7 +251,8 @@ public interface PluginManager { /** * Subscribes to the given Default permissions by operator status * <p> - * If the specified defaults change in any form, the Permissible will be asked to recalculate. + * If the specified defaults change in any form, the Permissible will be + * asked to recalculate. * * @param op Default list to subscribe to * @param permissible Permissible subscribing @@ -250,7 +268,8 @@ public interface PluginManager { public void unsubscribeFromDefaultPerms(boolean op, Permissible permissible); /** - * Gets a set containing all subscribed {@link Permissible}s to the given default list, by op status + * Gets a set containing all subscribed {@link Permissible}s to the given + * default list, by op status * * @param op Default list to query for * @return Set containing all subscribed permissions diff --git a/src/main/java/org/bukkit/plugin/ServicesManager.java b/src/main/java/org/bukkit/plugin/ServicesManager.java index c1a5fd65..5d45ffb2 100644 --- a/src/main/java/org/bukkit/plugin/ServicesManager.java +++ b/src/main/java/org/bukkit/plugin/ServicesManager.java @@ -4,8 +4,8 @@ import java.util.Collection; import java.util.List; /** - * Manages services and service providers. Services are an interface specifying - * a list of methods that a provider must implement. Providers are + * Manages services and service providers. Services are an interface + * specifying a list of methods that a provider must implement. Providers are * implementations of these services. A provider can be queried from the * services manager in order to use a service (if one is available). If * multiple plugins register a service, then the service with the highest diff --git a/src/main/java/org/bukkit/plugin/SimplePluginManager.java b/src/main/java/org/bukkit/plugin/SimplePluginManager.java index 93fb4f5a..3c9611ba 100644 --- a/src/main/java/org/bukkit/plugin/SimplePluginManager.java +++ b/src/main/java/org/bukkit/plugin/SimplePluginManager.java @@ -62,7 +62,8 @@ public final class SimplePluginManager implements PluginManager { * Registers the specified plugin loader * * @param loader Class name of the PluginLoader to register - * @throws IllegalArgumentException Thrown when the given Class is not a valid PluginLoader + * @throws IllegalArgumentException Thrown when the given Class is not a + * valid PluginLoader */ public void registerInterface(Class<? extends PluginLoader> loader) throws IllegalArgumentException { PluginLoader instance; @@ -284,8 +285,10 @@ public final class SimplePluginManager implements PluginManager { * * @param file File containing the plugin to load * @return The Plugin loaded, or null if it was invalid - * @throws InvalidPluginException Thrown when the specified file is not a valid plugin - * @throws UnknownDependencyException If a required dependency could not be found + * @throws InvalidPluginException Thrown when the specified file is not a + * valid plugin + * @throws UnknownDependencyException If a required dependency could not + * be found */ public synchronized Plugin loadPlugin(File file) throws InvalidPluginException, UnknownDependencyException { Validate.notNull(file, "File cannot be null"); @@ -443,7 +446,8 @@ public final class SimplePluginManager implements PluginManager { } /** - * Calls an event with the given details.<br> + * Calls an event with the given details. + * <p> * This method only synchronizes when the event is not asynchronous. * * @param event Event details @@ -510,14 +514,16 @@ public final class SimplePluginManager implements PluginManager { } /** - * Registers the given event to the specified listener using a directly passed EventExecutor + * Registers the given event to the specified listener using a directly + * passed EventExecutor * * @param event Event class to register * @param listener PlayerListener to register * @param priority Priority of this event * @param executor EventExecutor to register * @param plugin Plugin to register - * @param ignoreCancelled Do not call executor if event was already cancelled + * @param ignoreCancelled Do not call executor if event was already + * cancelled */ public void registerEvent(Class<? extends Event> event, Listener listener, EventPriority priority, EventExecutor executor, Plugin plugin, boolean ignoreCancelled) { Validate.notNull(listener, "Listener cannot be null"); diff --git a/src/main/java/org/bukkit/plugin/TimedRegisteredListener.java b/src/main/java/org/bukkit/plugin/TimedRegisteredListener.java index d86805b9..e09234c1 100644 --- a/src/main/java/org/bukkit/plugin/TimedRegisteredListener.java +++ b/src/main/java/org/bukkit/plugin/TimedRegisteredListener.java @@ -75,8 +75,7 @@ public class TimedRegisteredListener extends RegisteredListener { * multiple classes of event, the closest shared superclass will be * returned, such that for any event this listener has handled, * <code>this.getEventClass().isAssignableFrom(event.getClass())</code> - * and no class - * <code>this.getEventClass().isAssignableFrom(clazz) + * and no class <code>this.getEventClass().isAssignableFrom(clazz) * && this.getEventClass() != clazz && * event.getClass().isAssignableFrom(clazz)</code> for all handled events. * diff --git a/src/main/java/org/bukkit/plugin/UnknownDependencyException.java b/src/main/java/org/bukkit/plugin/UnknownDependencyException.java index 2cc759ad..a80251ef 100644 --- a/src/main/java/org/bukkit/plugin/UnknownDependencyException.java +++ b/src/main/java/org/bukkit/plugin/UnknownDependencyException.java @@ -8,7 +8,8 @@ public class UnknownDependencyException extends RuntimeException { private static final long serialVersionUID = 5721389371901775895L; /** - * Constructs a new UnknownDependencyException based on the given Exception + * Constructs a new UnknownDependencyException based on the given + * Exception * * @param throwable Exception that triggered this Exception */ @@ -26,7 +27,8 @@ public class UnknownDependencyException extends RuntimeException { } /** - * Constructs a new UnknownDependencyException based on the given Exception + * Constructs a new UnknownDependencyException based on the given + * Exception * * @param message Brief message explaining the cause of the exception * @param throwable Exception that triggered this Exception diff --git a/src/main/java/org/bukkit/plugin/java/JavaPlugin.java b/src/main/java/org/bukkit/plugin/java/JavaPlugin.java index 49d39893..3815da22 100644 --- a/src/main/java/org/bukkit/plugin/java/JavaPlugin.java +++ b/src/main/java/org/bukkit/plugin/java/JavaPlugin.java @@ -80,7 +80,8 @@ public abstract class JavaPlugin extends PluginBase { } /** - * Returns a value indicating whether or not this plugin is currently enabled + * Returns a value indicating whether or not this plugin is currently + * enabled * * @return true if this plugin is enabled, otherwise false */ @@ -228,7 +229,8 @@ public abstract class JavaPlugin extends PluginBase { * * @param loader PluginLoader that is responsible for this plugin * @param server Server instance that is running this plugin - * @param description PluginDescriptionFile containing metadata on this plugin + * @param description PluginDescriptionFile containing metadata on this + * plugin * @param dataFolder Folder containing the plugin's data * @param file File containing this plugin * @param classLoader ClassLoader which holds this plugin diff --git a/src/main/java/org/bukkit/plugin/messaging/Messenger.java b/src/main/java/org/bukkit/plugin/messaging/Messenger.java index c5b15250..aa009fea 100644 --- a/src/main/java/org/bukkit/plugin/messaging/Messenger.java +++ b/src/main/java/org/bukkit/plugin/messaging/Messenger.java @@ -5,10 +5,11 @@ import org.bukkit.entity.Player; import org.bukkit.plugin.Plugin; /** - * A class responsible for managing the registrations of plugin channels and their - * listeners. + * A class responsible for managing the registrations of plugin channels and + * their listeners. */ public interface Messenger { + /** * Represents the largest size that an individual Plugin Message may be. */ @@ -29,8 +30,8 @@ public interface Messenger { public boolean isReservedChannel(String channel); /** - * Registers the specific plugin to the requested outgoing plugin channel, allowing it - * to send messages through that channel to any clients. + * Registers the specific plugin to the requested outgoing plugin channel, + * allowing it to send messages through that channel to any clients. * * @param plugin Plugin that wishes to send messages through the channel. * @param channel Channel to register. @@ -39,18 +40,20 @@ public interface Messenger { public void registerOutgoingPluginChannel(Plugin plugin, String channel); /** - * Unregisters the specific plugin from the requested outgoing plugin channel, no longer - * allowing it to send messages through that channel to any clients. + * Unregisters the specific plugin from the requested outgoing plugin + * channel, no longer allowing it to send messages through that channel to + * any clients. * - * @param plugin Plugin that no longer wishes to send messages through the channel. + * @param plugin Plugin that no longer wishes to send messages through the + * channel. * @param channel Channel to unregister. * @throws IllegalArgumentException Thrown if plugin or channel is null. */ public void unregisterOutgoingPluginChannel(Plugin plugin, String channel); /** - * Unregisters the specific plugin from all outgoing plugin channels, no longer allowing - * it to send any plugin messages. + * Unregisters the specific plugin from all outgoing plugin channels, no + * longer allowing it to send any plugin messages. * * @param plugin Plugin that no longer wishes to send plugin messages. * @throws IllegalArgumentException Thrown if plugin is null. @@ -58,31 +61,36 @@ public interface Messenger { public void unregisterOutgoingPluginChannel(Plugin plugin); /** - * Registers the specific plugin for listening on the requested incoming plugin channel, - * allowing it to act upon any plugin messages. + * Registers the specific plugin for listening on the requested incoming + * plugin channel, allowing it to act upon any plugin messages. * * @param plugin Plugin that wishes to register to this channel. * @param channel Channel to register. * @param listener Listener to receive messages on. - * @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. + * @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); /** - * Unregisters the specific plugin's listener from listening on the requested incoming plugin channel, - * no longer allowing it to act upon any plugin messages. + * Unregisters the specific plugin's listener from listening on the + * requested incoming plugin channel, no longer allowing it to act upon + * any plugin messages. * * @param plugin Plugin that wishes to unregister from this channel. * @param channel Channel to unregister. * @param listener Listener to stop receiving messages on. - * @throws IllegalArgumentException Thrown if plugin, channel or listener is null. + * @throws IllegalArgumentException Thrown if plugin, channel or listener + * is null. */ public void unregisterIncomingPluginChannel(Plugin plugin, String channel, PluginMessageListener listener); /** - * Unregisters the specific plugin from listening on the requested incoming plugin channel, - * no longer allowing it to act upon any plugin messages. + * Unregisters the specific plugin from listening on the requested + * incoming plugin channel, no longer allowing it to act upon any plugin + * messages. * * @param plugin Plugin that wishes to unregister from this channel. * @param channel Channel to unregister. @@ -91,7 +99,8 @@ public interface Messenger { public void unregisterIncomingPluginChannel(Plugin plugin, String channel); /** - * Unregisters the specific plugin from listening on all plugin channels through all listeners. + * Unregisters the specific plugin from listening on all plugin channels + * through all listeners. * * @param plugin Plugin that wishes to unregister from this channel. * @throws IllegalArgumentException Thrown if plugin is null. @@ -106,10 +115,12 @@ public interface Messenger { public Set<String> getOutgoingChannels(); /** - * Gets a set containing all the outgoing plugin channels that the specified plugin is registered to. + * Gets a set containing all the outgoing plugin channels that the + * specified plugin is registered to. * * @param plugin Plugin to retrieve channels for. - * @return List of all registered outgoing plugin channels that a plugin is registered to. + * @return List of all registered outgoing plugin channels that a plugin + * is registered to. * @throws IllegalArgumentException Thrown if plugin is null. */ public Set<String> getOutgoingChannels(Plugin plugin); @@ -122,16 +133,19 @@ public interface Messenger { public Set<String> getIncomingChannels(); /** - * Gets a set containing all the incoming plugin channels that the specified plugin is registered for. + * Gets a set containing all the incoming plugin channels that the + * specified plugin is registered for. * * @param plugin Plugin to retrieve channels for. - * @return List of all registered incoming plugin channels that the plugin is registered for. + * @return List of all registered incoming plugin channels that the plugin + * is registered for. * @throws IllegalArgumentException Thrown if plugin is null. */ public Set<String> getIncomingChannels(Plugin plugin); /** - * Gets a set containing all the incoming plugin channel registrations that the specified plugin has. + * Gets a set containing all the incoming plugin channel registrations + * that the specified plugin has. * * @param plugin Plugin to retrieve registrations for. * @return List of all registrations that the plugin has. @@ -140,7 +154,8 @@ public interface Messenger { public Set<PluginMessageListenerRegistration> getIncomingChannelRegistrations(Plugin plugin); /** - * Gets a set containing all the incoming plugin channel registrations that are on the requested channel. + * Gets a set containing all the incoming plugin channel registrations + * that are on the requested channel. * * @param channel Channel to retrieve registrations for. * @return List of all registrations that are on the channel. @@ -149,8 +164,8 @@ public interface Messenger { public Set<PluginMessageListenerRegistration> getIncomingChannelRegistrations(String channel); /** - * Gets a set containing all the incoming plugin channel registrations that the specified plugin has - * on the requested channel. + * Gets a set containing all the incoming plugin channel registrations + * that the specified plugin has on the requested channel. * * @param plugin Plugin to retrieve registrations for. * @param channel Channel to filter registrations by. @@ -162,8 +177,8 @@ public interface Messenger { /** * Checks if the specified plugin message listener registration is valid. * <p> - * A registration is considered valid if it has not be unregistered and that the plugin - * is still enabled. + * A registration is considered valid if it has not be unregistered and + * that the plugin is still enabled. * * @param registration Registration to check. * @return True if the registration is valid, otherwise false. @@ -171,8 +186,8 @@ public interface Messenger { public boolean isRegistrationValid(PluginMessageListenerRegistration registration); /** - * Checks if the specified plugin has registered to receive incoming messages through the requested - * channel. + * Checks if the specified plugin has registered to receive incoming + * messages through the requested channel. * * @param plugin Plugin to check registration for. * @param channel Channel to test for. @@ -181,8 +196,8 @@ public interface Messenger { public boolean isIncomingChannelRegistered(Plugin plugin, String channel); /** - * Checks if the specified plugin has registered to send outgoing messages through the requested - * channel. + * Checks if the specified plugin has registered to send outgoing messages + * through the requested channel. * * @param plugin Plugin to check registration for. * @param channel Channel to test for. diff --git a/src/main/java/org/bukkit/plugin/messaging/PluginChannelDirection.java b/src/main/java/org/bukkit/plugin/messaging/PluginChannelDirection.java index 3b385484..3d7ec2e2 100644 --- a/src/main/java/org/bukkit/plugin/messaging/PluginChannelDirection.java +++ b/src/main/java/org/bukkit/plugin/messaging/PluginChannelDirection.java @@ -4,6 +4,7 @@ package org.bukkit.plugin.messaging; * Represents the different directions a plugin channel may go. */ public enum PluginChannelDirection { + /** * The plugin channel is being sent to the server from a client. */ diff --git a/src/main/java/org/bukkit/plugin/messaging/PluginMessageListener.java b/src/main/java/org/bukkit/plugin/messaging/PluginMessageListener.java index 462b5793..f1aa0806 100644 --- a/src/main/java/org/bukkit/plugin/messaging/PluginMessageListener.java +++ b/src/main/java/org/bukkit/plugin/messaging/PluginMessageListener.java @@ -3,10 +3,11 @@ package org.bukkit.plugin.messaging; import org.bukkit.entity.Player; /** - * A listener for a specific Plugin Channel, which will receive notifications of messages sent - * from a client. + * A listener for a specific Plugin Channel, which will receive notifications + * of messages sent from a client. */ public interface PluginMessageListener { + /** * A method that will be thrown when a PluginMessageSource sends a plugin * message on a registered channel. diff --git a/src/main/java/org/bukkit/plugin/messaging/PluginMessageListenerRegistration.java b/src/main/java/org/bukkit/plugin/messaging/PluginMessageListenerRegistration.java index 850ba5e3..29929bf7 100644 --- a/src/main/java/org/bukkit/plugin/messaging/PluginMessageListenerRegistration.java +++ b/src/main/java/org/bukkit/plugin/messaging/PluginMessageListenerRegistration.java @@ -3,7 +3,8 @@ package org.bukkit.plugin.messaging; import org.bukkit.plugin.Plugin; /** - * Contains information about a {@link Plugin}s registration to a plugin channel. + * Contains information about a {@link Plugin}s registration to a plugin + * channel. */ public final class PluginMessageListenerRegistration { private final Messenger messenger; diff --git a/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java b/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java index 6383166b..e5c59165 100644 --- a/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java +++ b/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java @@ -8,23 +8,29 @@ import org.bukkit.plugin.Plugin; */ public interface PluginMessageRecipient { /** - * Sends this recipient a Plugin Message on the specified outgoing channel. + * Sends this recipient a Plugin Message on the specified outgoing + * channel. * <p> - * The message may not be larger than {@link Messenger#MAX_MESSAGE_SIZE} bytes, and the plugin must be registered to send - * messages on the specified channel. + * The message may not be larger than {@link Messenger#MAX_MESSAGE_SIZE} + * bytes, and the plugin must be registered to send messages on the + * specified channel. * * @param source The plugin that sent this message. * @param channel The channel to send this message on. * @param message The raw message to send. - * @throws IllegalArgumentException Thrown if the source plugin is disabled. - * @throws IllegalArgumentException Thrown if source, channel or message is null. + * @throws IllegalArgumentException Thrown if the source plugin is + * disabled. + * @throws IllegalArgumentException Thrown if source, channel or message + * is null. * @throws MessageTooLargeException Thrown if the message is too big. - * @throws ChannelNotRegisteredException Thrown if the channel is not registered for this plugin. + * @throws ChannelNotRegisteredException Thrown if the channel is not + * registered for this plugin. */ public void sendPluginMessage(Plugin source, String channel, byte[] message); /** - * Gets a set containing all the Plugin Channels that this client is listening on. + * Gets a set containing all the Plugin Channels that this client is + * listening on. * * @return Set containing all the channels that this client may accept. */ diff --git a/src/main/java/org/bukkit/plugin/messaging/ReservedChannelException.java b/src/main/java/org/bukkit/plugin/messaging/ReservedChannelException.java index 7cf7845e..0221f049 100644 --- a/src/main/java/org/bukkit/plugin/messaging/ReservedChannelException.java +++ b/src/main/java/org/bukkit/plugin/messaging/ReservedChannelException.java @@ -1,7 +1,8 @@ package org.bukkit.plugin.messaging; /** - * Thrown if a plugin attempts to register for a reserved channel (such as "REGISTER") + * Thrown if a plugin attempts to register for a reserved channel (such as + * "REGISTER") */ @SuppressWarnings("serial") public class ReservedChannelException extends RuntimeException { diff --git a/src/main/java/org/bukkit/plugin/messaging/StandardMessenger.java b/src/main/java/org/bukkit/plugin/messaging/StandardMessenger.java index e90f2e10..a906f8dd 100644 --- a/src/main/java/org/bukkit/plugin/messaging/StandardMessenger.java +++ b/src/main/java/org/bukkit/plugin/messaging/StandardMessenger.java @@ -440,17 +440,22 @@ public class StandardMessenger implements Messenger { } /** - * Validates the input of a Plugin Message, ensuring the arguments are all valid. + * Validates the input of a Plugin Message, ensuring the arguments are all + * valid. * * @param messenger Messenger to use for validation. * @param source Source plugin of the Message. * @param channel Plugin Channel to send the message by. * @param message Raw message payload to send. - * @throws IllegalArgumentException Thrown if the source plugin is disabled. - * @throws IllegalArgumentException Thrown if source, channel or message is null. + * @throws IllegalArgumentException Thrown if the source plugin is + * disabled. + * @throws IllegalArgumentException Thrown if source, channel or message + * is null. * @throws MessageTooLargeException Thrown if the message is too big. - * @throws ChannelNameTooLongException Thrown if the channel name is too long. - * @throws ChannelNotRegisteredException Thrown if the channel is not registered for this plugin. + * @throws ChannelNameTooLongException Thrown if the channel name is too + * long. + * @throws ChannelNotRegisteredException Thrown if the channel is not + * registered for this plugin. */ public static void validatePluginMessage(Messenger messenger, Plugin source, String channel, byte[] message) { if (messenger == null) { diff --git a/src/main/java/org/bukkit/potion/Potion.java b/src/main/java/org/bukkit/potion/Potion.java index 0d44ce0b..a358c299 100644 --- a/src/main/java/org/bukkit/potion/Potion.java +++ b/src/main/java/org/bukkit/potion/Potion.java @@ -20,9 +20,10 @@ public class Potion { private PotionType type; /** - * Construct a new potion of the given type. Unless the type is {@link PotionType#WATER}, - * it will be level one, without extended duration. Don't use this constructor to create - * a no-effect potion other than water bottle. + * Construct a new potion of the given type. Unless the type is {@link + * PotionType#WATER}, it will be level one, without extended duration. + * Don't use this constructor to create a no-effect potion other than + * water bottle. * * @param type The potion type * @see #Potion(int) @@ -57,7 +58,8 @@ public class Potion { } /** - * @deprecated In favour of {@link #Potion(PotionType, int, boolean, boolean)} + * @deprecated In favour of {@link #Potion(PotionType, int, boolean, + * boolean)} */ @SuppressWarnings("javadoc") @Deprecated @@ -86,7 +88,8 @@ public class Potion { * @param type The type of potion. * @param level The potion's level. * @param splash Whether it is a splash potion. - * @deprecated In favour of using {@link #Potion(PotionType)} with {@link #splash()}. + * @deprecated In favour of using {@link #Potion(PotionType)} with {@link + * #splash()}. */ @Deprecated public Potion(PotionType type, int level, boolean splash) { @@ -101,8 +104,8 @@ 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 #extend()} - * and possibly {@link #splash()}. + * @deprecated In favour of using {@link #Potion(PotionType)} with {@link + * #extend()} and possibly {@link #splash()}. */ @Deprecated public Potion(PotionType type, int level, boolean splash, boolean extended) { @@ -146,7 +149,7 @@ public class Potion { /** * Applies the effects of this potion to the given {@link ItemStack}. The - * itemstack must be a potion. + * ItemStack must be a potion. * * @param to The itemstack to apply to */ @@ -250,8 +253,8 @@ 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. + * 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 */ @@ -261,11 +264,10 @@ public class Potion { } /** - * Sets whether this potion is a splash potion. Splash potions can be thrown - * for a radius effect. + * Sets whether this potion is a splash potion. Splash potions can be + * thrown for a radius effect. * - * @param isSplash - * Whether this is a splash potion + * @param isSplash Whether this is a splash potion */ public void setSplash(boolean isSplash) { splash = isSplash; @@ -286,8 +288,7 @@ public class Potion { /** * Sets the {@link PotionType} of this potion. * - * @param type - * The new type of this potion + * @param type The new type of this potion */ public void setType(PotionType type) { this.type = type; diff --git a/src/main/java/org/bukkit/potion/PotionBrewer.java b/src/main/java/org/bukkit/potion/PotionBrewer.java index ba5f20c9..52755170 100644 --- a/src/main/java/org/bukkit/potion/PotionBrewer.java +++ b/src/main/java/org/bukkit/potion/PotionBrewer.java @@ -19,8 +19,8 @@ public interface PotionBrewer { public PotionEffect createEffect(PotionEffectType potion, int duration, int amplifier); /** - * Returns a collection of {@link PotionEffect} that would be applied from a - * potion with the given data value. + * 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 The list of effects diff --git a/src/main/java/org/bukkit/potion/PotionEffect.java b/src/main/java/org/bukkit/potion/PotionEffect.java index af12be55..24ee19de 100644 --- a/src/main/java/org/bukkit/potion/PotionEffect.java +++ b/src/main/java/org/bukkit/potion/PotionEffect.java @@ -31,7 +31,8 @@ public class PotionEffect implements ConfigurationSerializable { * Creates a potion effect. * * @param type effect type - * @param duration measured in ticks, see {@link PotionEffect#getDuration()} + * @param duration measured in ticks, see {@link + * PotionEffect#getDuration()} * @param amplifier the amplifier, see {@link PotionEffect#getAmplifier()} * @param ambient the ambient status, see {@link PotionEffect#isAmbient()} */ @@ -123,9 +124,9 @@ public class PotionEffect implements ConfigurationSerializable { } /** - * 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. + * 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 */ diff --git a/src/main/java/org/bukkit/potion/PotionEffectType.java b/src/main/java/org/bukkit/potion/PotionEffectType.java index 87cff375..4919d59e 100644 --- a/src/main/java/org/bukkit/potion/PotionEffectType.java +++ b/src/main/java/org/bukkit/potion/PotionEffectType.java @@ -105,7 +105,8 @@ public abstract class PotionEffectType { public static final PotionEffectType POISON = new PotionEffectTypeWrapper(19); /** - * Deals damage to an entity over time and gives the health to the shooter. + * Deals damage to an entity over time and gives the health to the + * shooter. */ public static final PotionEffectType WITHER = new PotionEffectTypeWrapper(20); @@ -132,7 +133,8 @@ public abstract class PotionEffectType { } /** - * Creates a PotionEffect from this PotionEffectType, applying duration modifiers and checks. + * Creates a PotionEffect from this PotionEffectType, applying duration + * modifiers and checks. * * @see PotionBrewer#createEffect(PotionEffectType, int, int) * @param duration time in ticks diff --git a/src/main/java/org/bukkit/scheduler/BukkitRunnable.java b/src/main/java/org/bukkit/scheduler/BukkitRunnable.java index 218273fa..03519443 100644 --- a/src/main/java/org/bukkit/scheduler/BukkitRunnable.java +++ b/src/main/java/org/bukkit/scheduler/BukkitRunnable.java @@ -33,10 +33,10 @@ public abstract class BukkitRunnable implements Runnable { } /** - * <b>Asynchronous tasks should never access any API in Bukkit. - * Great care should be taken to assure the thread-safety of asynchronous tasks.</b> - * <br> - * <br>Schedules this in the Bukkit scheduler to run asynchronously. + * <b>Asynchronous tasks should never access any API in Bukkit. Great care + * should be taken to assure the thread-safety of asynchronous tasks.</b> + * <p> + * Schedules this in the Bukkit scheduler to run asynchronously. * * @param plugin the reference to the plugin scheduling task * @return a BukkitTask that contains the id number @@ -65,10 +65,11 @@ public abstract class BukkitRunnable implements Runnable { } /** - * <b>Asynchronous tasks should never access any API in Bukkit. - * Great care should be taken to assure the thread-safety of asynchronous tasks.</b> - * <br> - * <br>Schedules this to run asynchronously after the specified number of server ticks. + * <b>Asynchronous tasks should never access any API in Bukkit. Great care + * should be taken to assure the thread-safety of asynchronous tasks.</b> + * <p> + * Schedules this to run asynchronously after the specified number of + * server ticks. * * @param plugin the reference to the plugin scheduling task * @param delay the ticks to wait before running the task @@ -83,7 +84,8 @@ public abstract class BukkitRunnable implements Runnable { } /** - * Schedules this to repeatedly run until cancelled, starting after the specified number of server ticks. + * Schedules this to repeatedly run until cancelled, starting after the + * specified number of server ticks. * * @param plugin the reference to the plugin scheduling task * @param delay the ticks to wait before running the task @@ -99,18 +101,21 @@ public abstract class BukkitRunnable implements Runnable { } /** - * <b>Asynchronous tasks should never access any API in Bukkit. - * Great care should be taken to assure the thread-safety of asynchronous tasks.</b> - * <br> - * <br>Schedules this to repeatedly run asynchronously until cancelled, starting after the specified number of server ticks. + * <b>Asynchronous tasks should never access any API in Bukkit. Great care + * should be taken to assure the thread-safety of asynchronous tasks.</b> + * <p> + * Schedules this to repeatedly run asynchronously until cancelled, + * starting after the specified number of server ticks. * * @param plugin the reference to the plugin scheduling task - * @param delay the ticks to wait before running the task for the first time + * @param delay the ticks to wait before running the task for the first + * time * @param period the ticks to wait between runs * @return a BukkitTask that contains the id number * @throws IllegalArgumentException if plugin is null * @throws IllegalStateException if this was already scheduled - * @see BukkitScheduler#runTaskTimerAsynchronously(Plugin, Runnable, long, long) + * @see BukkitScheduler#runTaskTimerAsynchronously(Plugin, Runnable, long, + * long) */ public synchronized BukkitTask runTaskTimerAsynchronously(Plugin plugin, long delay, long period) throws IllegalArgumentException, IllegalStateException { checkState(); diff --git a/src/main/java/org/bukkit/scheduler/BukkitScheduler.java b/src/main/java/org/bukkit/scheduler/BukkitScheduler.java index ff58f326..44d94f08 100644 --- a/src/main/java/org/bukkit/scheduler/BukkitScheduler.java +++ b/src/main/java/org/bukkit/scheduler/BukkitScheduler.java @@ -9,6 +9,7 @@ public interface BukkitScheduler { /** * Schedules a once off task to occur after a delay. + * <p> * This task will be executed by the main server thread. * * @param plugin Plugin that owns the task @@ -20,6 +21,7 @@ public interface BukkitScheduler { /** * Schedules a once off task to occur as soon as possible. + * <p> * This task will be executed by the main server thread. * * @param plugin Plugin that owns the task @@ -30,6 +32,7 @@ public interface BukkitScheduler { /** * Schedules a repeating task. + * <p> * This task will be executed by the main server thread. * * @param plugin Plugin that owns the task @@ -41,60 +44,65 @@ public interface BukkitScheduler { public int scheduleSyncRepeatingTask(Plugin plugin, Runnable task, long delay, long period); /** - * <b>Asynchronous tasks should never access any API in Bukkit. - * Great care should be taken to assure the thread-safety of asynchronous tasks.</b> - * <br> - * <br>Schedules a once off task to occur after a delay. - * This task will be executed by a thread managed by the scheduler. + * <b>Asynchronous tasks should never access any API in Bukkit. Great care + * should be taken to assure the thread-safety of asynchronous tasks.</b> + * <p> + * Schedules a once off task to occur after a delay. This task will be + * executed by a thread managed by the scheduler. * * @param plugin Plugin that owns the task * @param task Task to be executed * @param delay Delay in server ticks before executing task * @return Task id number (-1 if scheduling failed) - * @deprecated This name is misleading, as it does not schedule "a sync" task, but rather, "an async" task + * @deprecated This name is misleading, as it does not schedule "a sync" + * task, but rather, "an async" task */ @Deprecated public int scheduleAsyncDelayedTask(Plugin plugin, Runnable task, long delay); /** - * <b>Asynchronous tasks should never access any API in Bukkit. - * Great care should be taken to assure the thread-safety of asynchronous tasks.</b> - * <br> - * <br>Schedules a once off task to occur as soon as possible. - * This task will be executed by a thread managed by the scheduler. + * <b>Asynchronous tasks should never access any API in Bukkit. Great care + * should be taken to assure the thread-safety of asynchronous tasks.</b> + * <p> + * Schedules a once off task to occur as soon as possible. This task will + * be executed by a thread managed by the scheduler. * * @param plugin Plugin that owns the task * @param task Task to be executed * @return Task id number (-1 if scheduling failed) - * @deprecated This name is misleading, as it does not schedule "a sync" task, but rather, "an async" task + * @deprecated This name is misleading, as it does not schedule "a sync" + * task, but rather, "an async" task */ @Deprecated public int scheduleAsyncDelayedTask(Plugin plugin, Runnable task); /** - * <b>Asynchronous tasks should never access any API in Bukkit. - * Great care should be taken to assure the thread-safety of asynchronous tasks.</b> - * <br> - * <br>Schedules a repeating task. - * This task will be executed by a thread managed by the scheduler. + * <b>Asynchronous tasks should never access any API in Bukkit. Great care + * should be taken to assure the thread-safety of asynchronous tasks.</b> + * <p> + * Schedules a repeating task. This task will be executed by a thread + * managed by the scheduler. * * @param plugin Plugin that owns the task * @param task Task to be executed * @param delay Delay in server ticks before executing first repeat * @param period Period in server ticks of the task * @return Task id number (-1 if scheduling failed) - * @deprecated This name is misleading, as it does not schedule "a sync" task, but rather, "an async" task + * @deprecated This name is misleading, as it does not schedule "a sync" + * task, but rather, "an async" task */ @Deprecated public int scheduleAsyncRepeatingTask(Plugin plugin, Runnable task, long delay, long period); /** - * Calls a method on the main thread and returns a Future object - * This task will be executed by the main server thread. - * <p> - * Note: The Future.get() methods must NOT be called from the main thread. - * Note2: There is at least an average of 10ms latency until the isDone() method returns true. - * + * Calls a method on the main thread and returns a Future object. This + * task will be executed by the main server thread. + * <ul> + * <li>Note: The Future.get() methods must NOT be called from the main + * thread. + * <li>Note2: There is at least an average of 10ms latency until the + * isDone() method returns true. + * </ul> * @param <T> The callable's return type * @param plugin Plugin that owns the task * @param task Task to be executed @@ -110,7 +118,8 @@ public interface BukkitScheduler { public void cancelTask(int taskId); /** - * Removes all tasks associated with a particular plugin from the scheduler. + * Removes all tasks associated with a particular plugin from the + * scheduler. * * @param plugin Owner of tasks to be removed */ @@ -124,10 +133,12 @@ public interface BukkitScheduler { /** * Check if the task currently running. * <p> - * A repeating task might not be running currently, but will be running in the future. - * A task that has finished, and does not repeat, will not be running ever again. + * A repeating task might not be running currently, but will be running in + * the future. A task that has finished, and does not repeat, will not be + * running ever again. * <p> - * Explicitly, a task is running if there exists a thread for it, and that thread is alive. + * Explicitly, a task is running if there exists a thread for it, and that + * thread is alive. * * @param taskId The task to check. * <p> @@ -138,8 +149,9 @@ public interface BukkitScheduler { /** * Check if the task queued to be run later. * <p> - * If a repeating task is currently running, it might not be queued now but could be in the future. - * A task that is not queued, and not running, will not be queued again. + * If a repeating task is currently running, it might not be queued now + * but could be in the future. A task that is not queued, and not running, + * will not be queued again. * * @param taskId The task to check. * <p> @@ -150,14 +162,16 @@ public interface BukkitScheduler { /** * Returns a list of all active workers. * <p> - * This list contains asynch tasks that are being executed by separate threads. + * This list contains asynch tasks that are being executed by separate + * threads. * * @return Active workers */ public List<BukkitWorker> getActiveWorkers(); /** - * Returns a list of all pending tasks. The ordering of the tasks is not related to their order of execution. + * Returns a list of all pending tasks. The ordering of the tasks is not + * related to their order of execution. * * @return Active workers */ @@ -175,10 +189,10 @@ public interface BukkitScheduler { public BukkitTask runTask(Plugin plugin, Runnable task) throws IllegalArgumentException; /** - * <b>Asynchronous tasks should never access any API in Bukkit. - * Great care should be taken to assure the thread-safety of asynchronous tasks.</b> - * <br> - * <br>Returns a task that will run asynchronously. + * <b>Asynchronous tasks should never access any API in Bukkit. Great care + * should be taken to assure the thread-safety of asynchronous tasks.</b> + * <p> + * Returns a task that will run asynchronously. * * @param plugin the reference to the plugin scheduling task * @param task the task to be run @@ -189,7 +203,8 @@ public interface BukkitScheduler { public BukkitTask runTaskAsynchronously(Plugin plugin, Runnable task) throws IllegalArgumentException; /** - * Returns a task that will run after the specified number of server ticks. + * Returns a task that will run after the specified number of server + * ticks. * * @param plugin the reference to the plugin scheduling task * @param task the task to be run @@ -201,10 +216,11 @@ public interface BukkitScheduler { public BukkitTask runTaskLater(Plugin plugin, Runnable task, long delay) throws IllegalArgumentException; /** - * <b>Asynchronous tasks should never access any API in Bukkit. - * Great care should be taken to assure the thread-safety of asynchronous tasks.</b> - * <br> - * <br>Returns a task that will run asynchronously after the specified number of server ticks. + * <b>Asynchronous tasks should never access any API in Bukkit. Great care + * should be taken to assure the thread-safety of asynchronous tasks.</b> + * <p> + * Returns a task that will run asynchronously after the specified number + * of server ticks. * * @param plugin the reference to the plugin scheduling task * @param task the task to be run @@ -216,7 +232,8 @@ public interface BukkitScheduler { public BukkitTask runTaskLaterAsynchronously(Plugin plugin, Runnable task, long delay) throws IllegalArgumentException; /** - * Returns a task that will repeatedly run until cancelled, starting after the specified number of server ticks. + * Returns a task that will repeatedly run until cancelled, starting after + * the specified number of server ticks. * * @param plugin the reference to the plugin scheduling task * @param task the task to be run @@ -229,14 +246,16 @@ public interface BukkitScheduler { public BukkitTask runTaskTimer(Plugin plugin, Runnable task, long delay, long period) throws IllegalArgumentException; /** - * <b>Asynchronous tasks should never access any API in Bukkit. - * Great care should be taken to assure the thread-safety of asynchronous tasks.</b> - * <br> - * <br>Returns a task that will repeatedly run asynchronously until cancelled, starting after the specified number of server ticks. + * <b>Asynchronous tasks should never access any API in Bukkit. Great care + * should be taken to assure the thread-safety of asynchronous tasks.</b> + * <p> + * Returns a task that will repeatedly run asynchronously until cancelled, + * starting after the specified number of server ticks. * * @param plugin the reference to the plugin scheduling task * @param task the task to be run - * @param delay the ticks to wait before running the task for the first time + * @param delay the ticks to wait before running the task for the first + * time * @param period the ticks to wait between runs * @return a BukkitTask that contains the id number * @throws IllegalArgumentException if plugin is null diff --git a/src/main/java/org/bukkit/scheduler/BukkitWorker.java b/src/main/java/org/bukkit/scheduler/BukkitWorker.java index 4df43a6a..fe1afbd5 100644 --- a/src/main/java/org/bukkit/scheduler/BukkitWorker.java +++ b/src/main/java/org/bukkit/scheduler/BukkitWorker.java @@ -5,7 +5,7 @@ import org.bukkit.plugin.Plugin; /** * Represents a worker thread for the scheduler. This gives information about * the Thread object for the task, owner of the task and the taskId. - * </p> + * <p> * Workers are used to execute async tasks. */ public interface BukkitWorker { diff --git a/src/main/java/org/bukkit/scoreboard/Scoreboard.java b/src/main/java/org/bukkit/scoreboard/Scoreboard.java index 3e75cf5d..e9b0abdc 100644 --- a/src/main/java/org/bukkit/scoreboard/Scoreboard.java +++ b/src/main/java/org/bukkit/scoreboard/Scoreboard.java @@ -17,7 +17,8 @@ public interface Scoreboard { * @return The registered Objective * @throws IllegalArgumentException if name is null * @throws IllegalArgumentException if criteria is null - * @throws IllegalArgumentException if an objective by that name already exists + * @throws IllegalArgumentException if an objective by that name already + * exists */ Objective registerNewObjective(String name, String criteria) throws IllegalArgumentException; @@ -46,10 +47,12 @@ public interface Scoreboard { Set<Objective> getObjectives(); /** - * Gets the Objective currently displayed in a DisplaySlot on this Scoreboard + * Gets the Objective currently displayed in a DisplaySlot on this + * Scoreboard * * @param slot The DisplaySlot - * @return the Objective currently displayed or null if nothing is displayed in that DisplaySlot + * @return the Objective currently displayed or null if nothing is + * displayed in that DisplaySlot * @throws IllegalArgumentException if slot is null */ Objective getObjective(DisplaySlot slot) throws IllegalArgumentException; diff --git a/src/main/java/org/bukkit/util/BlockIterator.java b/src/main/java/org/bukkit/util/BlockIterator.java index d8c33cb9..5c85778c 100644 --- a/src/main/java/org/bukkit/util/BlockIterator.java +++ b/src/main/java/org/bukkit/util/BlockIterator.java @@ -44,8 +44,11 @@ public class BlockIterator implements Iterator<Block> { * @param world The world to use for tracing * @param start A Vector giving the initial location for the trace * @param direction A Vector pointing in the direction for the trace - * @param yOffset The trace begins vertically offset from the start vector by this value - * @param maxDistance This is the maximum distance in blocks for the trace. Setting this value above 140 may lead to problems with unloaded chunks. A value of 0 indicates no limit + * @param yOffset The trace begins vertically offset from the start vector + * by this value + * @param maxDistance This is the maximum distance in blocks for the + * trace. Setting this value above 140 may lead to problems with + * unloaded chunks. A value of 0 indicates no limit * */ public BlockIterator(World world, Vector start, Vector direction, double yOffset, int maxDistance) { @@ -220,8 +223,11 @@ public class BlockIterator implements Iterator<Block> { * Constructs the BlockIterator * * @param loc The location for the start of the ray trace - * @param yOffset The trace begins vertically offset from the start vector by this value - * @param maxDistance This is the maximum distance in blocks for the trace. Setting this value above 140 may lead to problems with unloaded chunks. A value of 0 indicates no limit + * @param yOffset The trace begins vertically offset from the start vector + * by this value + * @param maxDistance This is the maximum distance in blocks for the + * trace. Setting this value above 140 may lead to problems with + * unloaded chunks. A value of 0 indicates no limit */ public BlockIterator(Location loc, double yOffset, int maxDistance) { this(loc.getWorld(), loc.toVector(), loc.getDirection(), yOffset, maxDistance); @@ -231,7 +237,8 @@ public class BlockIterator implements Iterator<Block> { * Constructs the BlockIterator. * * @param loc The location for the start of the ray trace - * @param yOffset The trace begins vertically offset from the start vector by this value + * @param yOffset The trace begins vertically offset from the start vector + * by this value */ public BlockIterator(Location loc, double yOffset) { @@ -252,7 +259,9 @@ public class BlockIterator implements Iterator<Block> { * Constructs the BlockIterator. * * @param entity Information from the entity is used to set up the trace - * @param maxDistance This is the maximum distance in blocks for the trace. Setting this value above 140 may lead to problems with unloaded chunks. A value of 0 indicates no limit + * @param maxDistance This is the maximum distance in blocks for the + * trace. Setting this value above 140 may lead to problems with + * unloaded chunks. A value of 0 indicates no limit */ public BlockIterator(LivingEntity entity, int maxDistance) { diff --git a/src/main/java/org/bukkit/util/ChatPaginator.java b/src/main/java/org/bukkit/util/ChatPaginator.java index 8f58d78f..24802d15 100644 --- a/src/main/java/org/bukkit/util/ChatPaginator.java +++ b/src/main/java/org/bukkit/util/ChatPaginator.java @@ -6,8 +6,9 @@ import java.util.LinkedList; import java.util.List; /** - * The ChatPaginator takes a raw string of arbitrary length and breaks it down into an array of strings appropriate - * for displaying on the Minecraft player console. + * The ChatPaginator takes a raw string of arbitrary length and breaks it down + * into an array of strings appropriate for displaying on the Minecraft player + * console. */ public class ChatPaginator { public static final int GUARANTEED_NO_WRAP_CHAT_PAGE_WIDTH = 55; // Will never wrap, even with the largest characters @@ -51,8 +52,8 @@ public class ChatPaginator { } /** - * Breaks a raw string up into a series of lines. Words are wrapped using spaces as decimeters and the newline - * character is respected. + * Breaks a raw string up into a series of lines. Words are wrapped using + * spaces as decimeters and the newline character is respected. * * @param rawString The raw string to break. * @param lineLength The length of a line of text. diff --git a/src/main/java/org/bukkit/util/StringUtil.java b/src/main/java/org/bukkit/util/StringUtil.java index 12bc58d4..ed309ccb 100644 --- a/src/main/java/org/bukkit/util/StringUtil.java +++ b/src/main/java/org/bukkit/util/StringUtil.java @@ -6,15 +6,20 @@ import org.apache.commons.lang.Validate; public class StringUtil { /** - * Copies all elements from the iterable collection of originals to the collection provided. + * Copies all elements from the iterable collection of originals to the + * collection provided. * * @param token String to search for * @param originals An iterable collection of strings to filter. * @param collection The collection to add matches to - * @return the collection provided that would have the elements copied into - * @throws UnsupportedOperationException if the collection is immutable and originals contains a string which starts with the specified search string. + * @return the collection provided that would have the elements copied + * into + * @throws UnsupportedOperationException if the collection is immutable + * and originals contains a string which starts with the specified + * search string. * @throws IllegalArgumentException if any parameter is is null - * @throws IllegalArgumentException if originals contains a null element. <b>Note: the collection may be modified before this is thrown</b> + * @throws IllegalArgumentException if originals contains a null element. + * <b>Note: the collection may be modified before this is thrown</b> */ public static <T extends Collection<String>> T copyPartialMatches(final String token, final Iterable<String> originals, final T collection) throws UnsupportedOperationException, IllegalArgumentException { Validate.notNull(token, "Search token cannot be null"); @@ -31,11 +36,14 @@ public class StringUtil { } /** - * This method uses a substring to check case-insensitive equality. This means the internal array does not need to be copied like a toLowerCase() call would. + * This method uses a substring to check case-insensitive equality. This + * means the internal array does not need to be copied like a + * toLowerCase() call would. * * @param string String to check * @param prefix Prefix of string to compare - * @return true if provided string starts with, ignoring case, the prefix provided + * @return true if provided string starts with, ignoring case, the prefix + * provided * @throws NullPointerException if prefix is null * @throws IllegalArgumentException if string is null */ diff --git a/src/main/java/org/bukkit/util/Vector.java b/src/main/java/org/bukkit/util/Vector.java index de30d2ba..61116ea3 100644 --- a/src/main/java/org/bukkit/util/Vector.java +++ b/src/main/java/org/bukkit/util/Vector.java @@ -143,11 +143,11 @@ public class Vector implements Cloneable, ConfigurationSerializable { } /** - * Gets the magnitude of the vector, defined as sqrt(x^2+y^2+z^2). The value - * of this method is not cached and uses a costly square-root function, so - * do not repeatedly call this method to get the vector's magnitude. NaN - * will be returned if the inner result of the sqrt() function overflows, - * which will be caused if the length is too long. + * Gets the magnitude of the vector, defined as sqrt(x^2+y^2+z^2). The + * value of this method is not cached and uses a costly square-root + * function, so do not repeatedly call this method to get the vector's + * magnitude. NaN will be returned if the inner result of the sqrt() + * function overflows, which will be caused if the length is too long. * * @return the magnitude */ @@ -165,11 +165,11 @@ public class Vector implements Cloneable, ConfigurationSerializable { } /** - * Get the distance between this vector and another. The value - * of this method is not cached and uses a costly square-root function, so - * do not repeatedly call this method to get the vector's magnitude. NaN - * will be returned if the inner result of the sqrt() function overflows, - * which will be caused if the distance is too long. + * Get the distance between this vector and another. The value of this + * method is not cached and uses a costly square-root function, so do not + * repeatedly call this method to get the vector's magnitude. NaN will be + * returned if the inner result of the sqrt() function overflows, which + * will be caused if the distance is too long. * * @param o The other vector * @return the distance @@ -227,7 +227,8 @@ public class Vector implements Cloneable, ConfigurationSerializable { } /** - * Performs scalar multiplication, multiplying all components with a scalar. + * Performs scalar multiplication, multiplying all components with a + * scalar. * * @param m The factor * @return the same vector @@ -240,7 +241,8 @@ public class Vector implements Cloneable, ConfigurationSerializable { } /** - * Performs scalar multiplication, multiplying all components with a scalar. + * Performs scalar multiplication, multiplying all components with a + * scalar. * * @param m The factor * @return the same vector @@ -253,7 +255,8 @@ public class Vector implements Cloneable, ConfigurationSerializable { } /** - * Performs scalar multiplication, multiplying all components with a scalar. + * Performs scalar multiplication, multiplying all components with a + * scalar. * * @param m The factor * @return the same vector @@ -279,10 +282,11 @@ public class Vector implements Cloneable, ConfigurationSerializable { /** * Calculates the cross product of this vector with another. The cross * product is defined as: - * <p> - * x = y1 * z2 - y2 * z1<br/> - * y = z1 * x2 - z2 * x1<br/> - * z = x1 * y2 - x2 * y1 + * <ul> + * <li>x = y1 * z2 - y2 * z1 + * <li>y = z1 * x2 - z2 * x1 + * <li>z = x1 * y2 - x2 * y1 + * </ul> * * @param o The other vector * @return the same vector @@ -327,6 +331,7 @@ public class Vector implements Cloneable, ConfigurationSerializable { /** * Returns whether this vector is in an axis-aligned bounding box. + * <p> * The minimum and maximum vectors given must be truly the minimum and * maximum X, Y and Z components. * @@ -623,8 +628,8 @@ public class Vector implements Cloneable, ConfigurationSerializable { } /** - * Gets a random vector with components having a random value between - * 0 and 1. + * Gets a random vector with components having a random value between 0 + * and 1. * * @return A random vector. */ diff --git a/src/main/java/org/bukkit/util/noise/NoiseGenerator.java b/src/main/java/org/bukkit/util/noise/NoiseGenerator.java index b060ed77..72c92f33 100644 --- a/src/main/java/org/bukkit/util/noise/NoiseGenerator.java +++ b/src/main/java/org/bukkit/util/noise/NoiseGenerator.java @@ -66,7 +66,8 @@ public abstract class NoiseGenerator { public abstract double noise(double x, double y, double z); /** - * Generates noise for the 1D coordinates using the specified number of octaves and parameters + * Generates noise for the 1D coordinates using the specified number of + * octaves and parameters * * @param x X-coordinate * @param octaves Number of octaves to use @@ -79,7 +80,8 @@ public abstract class NoiseGenerator { } /** - * Generates noise for the 1D coordinates using the specified number of octaves and parameters + * Generates noise for the 1D coordinates using the specified number of + * octaves and parameters * * @param x X-coordinate * @param octaves Number of octaves to use @@ -93,7 +95,8 @@ public abstract class NoiseGenerator { } /** - * Generates noise for the 2D coordinates using the specified number of octaves and parameters + * Generates noise for the 2D coordinates using the specified number of + * octaves and parameters * * @param x X-coordinate * @param y Y-coordinate @@ -107,7 +110,8 @@ public abstract class NoiseGenerator { } /** - * Generates noise for the 2D coordinates using the specified number of octaves and parameters + * Generates noise for the 2D coordinates using the specified number of + * octaves and parameters * * @param x X-coordinate * @param y Y-coordinate @@ -122,7 +126,8 @@ public abstract class NoiseGenerator { } /** - * Generates noise for the 3D coordinates using the specified number of octaves and parameters + * Generates noise for the 3D coordinates using the specified number of + * octaves and parameters * * @param x X-coordinate * @param y Y-coordinate @@ -137,7 +142,8 @@ public abstract class NoiseGenerator { } /** - * Generates noise for the 3D coordinates using the specified number of octaves and parameters + * Generates noise for the 3D coordinates using the specified number of + * octaves and parameters * * @param x X-coordinate * @param y Y-coordinate diff --git a/src/main/java/org/bukkit/util/noise/OctaveGenerator.java b/src/main/java/org/bukkit/util/noise/OctaveGenerator.java index 4bb61c61..a87304ba 100644 --- a/src/main/java/org/bukkit/util/noise/OctaveGenerator.java +++ b/src/main/java/org/bukkit/util/noise/OctaveGenerator.java @@ -16,7 +16,8 @@ public abstract class OctaveGenerator { /** * Sets the scale used for all coordinates passed to this generator. * <p> - * This is the equivalent to setting each coordinate to the specified value. + * This is the equivalent to setting each coordinate to the specified + * value. * * @param scale New value to scale each coordinate by */ @@ -90,7 +91,8 @@ public abstract class OctaveGenerator { } /** - * Generates noise for the 1D coordinates using the specified number of octaves and parameters + * Generates noise for the 1D coordinates using the specified number of + * octaves and parameters * * @param x X-coordinate * @param frequency How much to alter the frequency by each octave @@ -102,7 +104,8 @@ public abstract class OctaveGenerator { } /** - * Generates noise for the 1D coordinates using the specified number of octaves and parameters + * Generates noise for the 1D coordinates using the specified number of + * octaves and parameters * * @param x X-coordinate * @param frequency How much to alter the frequency by each octave @@ -115,7 +118,8 @@ public abstract class OctaveGenerator { } /** - * Generates noise for the 2D coordinates using the specified number of octaves and parameters + * Generates noise for the 2D coordinates using the specified number of + * octaves and parameters * * @param x X-coordinate * @param y Y-coordinate @@ -128,7 +132,8 @@ public abstract class OctaveGenerator { } /** - * Generates noise for the 2D coordinates using the specified number of octaves and parameters + * Generates noise for the 2D coordinates using the specified number of + * octaves and parameters * * @param x X-coordinate * @param y Y-coordinate @@ -142,7 +147,8 @@ public abstract class OctaveGenerator { } /** - * Generates noise for the 3D coordinates using the specified number of octaves and parameters + * Generates noise for the 3D coordinates using the specified number of + * octaves and parameters * * @param x X-coordinate * @param y Y-coordinate @@ -156,7 +162,8 @@ public abstract class OctaveGenerator { } /** - * Generates noise for the 3D coordinates using the specified number of octaves and parameters + * Generates noise for the 3D coordinates using the specified number of + * octaves and parameters * * @param x X-coordinate * @param y Y-coordinate diff --git a/src/main/java/org/bukkit/util/noise/PerlinNoiseGenerator.java b/src/main/java/org/bukkit/util/noise/PerlinNoiseGenerator.java index ca6043e2..5e034c1e 100644 --- a/src/main/java/org/bukkit/util/noise/PerlinNoiseGenerator.java +++ b/src/main/java/org/bukkit/util/noise/PerlinNoiseGenerator.java @@ -6,7 +6,8 @@ import org.bukkit.World; /** * Generates noise using the "classic" perlin generator * - * @see SimplexNoiseGenerator "Improved" and faster version with slighly different results + * @see SimplexNoiseGenerator "Improved" and faster version with slighly + * different results */ public class PerlinNoiseGenerator extends NoiseGenerator { protected static final int grad3[][] = {{1, 1, 0}, {-1, 1, 0}, {1, -1, 0}, {-1, -1, 0}, @@ -82,7 +83,8 @@ public class PerlinNoiseGenerator extends NoiseGenerator { } /** - * Computes and returns the 1D unseeded perlin noise for the given coordinates in 1D space + * Computes and returns the 1D unseeded perlin noise for the given + * coordinates in 1D space * * @param x X coordinate * @return Noise at given location, from range -1 to 1 @@ -92,7 +94,8 @@ public class PerlinNoiseGenerator extends NoiseGenerator { } /** - * Computes and returns the 2D unseeded perlin noise for the given coordinates in 2D space + * Computes and returns the 2D unseeded perlin noise for the given + * coordinates in 2D space * * @param x X coordinate * @param y Y coordinate @@ -103,7 +106,8 @@ public class PerlinNoiseGenerator extends NoiseGenerator { } /** - * Computes and returns the 3D unseeded perlin noise for the given coordinates in 3D space + * Computes and returns the 3D unseeded perlin noise for the given + * coordinates in 3D space * * @param x X coordinate * @param y Y coordinate @@ -167,7 +171,8 @@ public class PerlinNoiseGenerator extends NoiseGenerator { } /** - * Generates noise for the 1D coordinates using the specified number of octaves and parameters + * Generates noise for the 1D coordinates using the specified number of + * octaves and parameters * * @param x X-coordinate * @param octaves Number of octaves to use @@ -180,7 +185,8 @@ public class PerlinNoiseGenerator extends NoiseGenerator { } /** - * Generates noise for the 2D coordinates using the specified number of octaves and parameters + * Generates noise for the 2D coordinates using the specified number of + * octaves and parameters * * @param x X-coordinate * @param y Y-coordinate @@ -194,7 +200,8 @@ public class PerlinNoiseGenerator extends NoiseGenerator { } /** - * Generates noise for the 3D coordinates using the specified number of octaves and parameters + * Generates noise for the 3D coordinates using the specified number of + * octaves and parameters * * @param x X-coordinate * @param y Y-coordinate diff --git a/src/main/java/org/bukkit/util/noise/PerlinOctaveGenerator.java b/src/main/java/org/bukkit/util/noise/PerlinOctaveGenerator.java index d959dae0..55b7ad7e 100644 --- a/src/main/java/org/bukkit/util/noise/PerlinOctaveGenerator.java +++ b/src/main/java/org/bukkit/util/noise/PerlinOctaveGenerator.java @@ -7,6 +7,7 @@ import org.bukkit.World; * Creates perlin noise through unbiased octaves */ public class PerlinOctaveGenerator extends OctaveGenerator { + /** * Creates a perlin octave generator for the given world * diff --git a/src/main/java/org/bukkit/util/noise/SimplexNoiseGenerator.java b/src/main/java/org/bukkit/util/noise/SimplexNoiseGenerator.java index 32c0c165..b052f3c3 100644 --- a/src/main/java/org/bukkit/util/noise/SimplexNoiseGenerator.java +++ b/src/main/java/org/bukkit/util/noise/SimplexNoiseGenerator.java @@ -7,7 +7,9 @@ import org.bukkit.World; * Generates simplex-based noise. * <p> * This is a modified version of the freely published version in the paper by - * Stefan Gustavson at http://staffwww.itn.liu.se/~stegu/simplexnoise/simplexnoise.pdf + * Stefan Gustavson at + * <a href="http://staffwww.itn.liu.se/~stegu/simplexnoise/simplexnoise.pdf"> + * http://staffwww.itn.liu.se/~stegu/simplexnoise/simplexnoise.pdf</a> */ public class SimplexNoiseGenerator extends PerlinNoiseGenerator { protected static final double SQRT_3 = Math.sqrt(3); @@ -87,7 +89,8 @@ public class SimplexNoiseGenerator extends PerlinNoiseGenerator { } /** - * Computes and returns the 1D unseeded simplex noise for the given coordinates in 1D space + * Computes and returns the 1D unseeded simplex noise for the given + * coordinates in 1D space * * @param xin X coordinate * @return Noise at given location, from range -1 to 1 @@ -97,7 +100,8 @@ public class SimplexNoiseGenerator extends PerlinNoiseGenerator { } /** - * Computes and returns the 2D unseeded simplex noise for the given coordinates in 2D space + * Computes and returns the 2D unseeded simplex noise for the given + * coordinates in 2D space * * @param xin X coordinate * @param yin Y coordinate @@ -108,7 +112,8 @@ public class SimplexNoiseGenerator extends PerlinNoiseGenerator { } /** - * Computes and returns the 3D unseeded simplex noise for the given coordinates in 3D space + * Computes and returns the 3D unseeded simplex noise for the given + * coordinates in 3D space * * @param xin X coordinate * @param yin Y coordinate @@ -120,7 +125,8 @@ public class SimplexNoiseGenerator extends PerlinNoiseGenerator { } /** - * Computes and returns the 4D simplex noise for the given coordinates in 4D space + * Computes and returns the 4D simplex noise for the given coordinates in + * 4D space * * @param x X coordinate * @param y Y coordinate @@ -348,7 +354,8 @@ public class SimplexNoiseGenerator extends PerlinNoiseGenerator { } /** - * Computes and returns the 4D simplex noise for the given coordinates in 4D space + * Computes and returns the 4D simplex noise for the given coordinates in + * 4D space * * @param x X coordinate * @param y Y coordinate diff --git a/src/main/java/org/bukkit/util/noise/SimplexOctaveGenerator.java b/src/main/java/org/bukkit/util/noise/SimplexOctaveGenerator.java index d041fbc2..61e66aa2 100644 --- a/src/main/java/org/bukkit/util/noise/SimplexOctaveGenerator.java +++ b/src/main/java/org/bukkit/util/noise/SimplexOctaveGenerator.java @@ -64,7 +64,8 @@ public class SimplexOctaveGenerator extends OctaveGenerator { } /** - * Generates noise for the 3D coordinates using the specified number of octaves and parameters + * Generates noise for the 3D coordinates using the specified number of + * octaves and parameters * * @param x X-coordinate * @param y Y-coordinate @@ -79,7 +80,8 @@ public class SimplexOctaveGenerator extends OctaveGenerator { } /** - * Generates noise for the 3D coordinates using the specified number of octaves and parameters + * Generates noise for the 3D coordinates using the specified number of + * octaves and parameters * * @param x X-coordinate * @param y Y-coordinate diff --git a/src/test/java/org/bukkit/TestServer.java b/src/test/java/org/bukkit/TestServer.java index c521e2b3..2d840320 100644 --- a/src/test/java/org/bukkit/TestServer.java +++ b/src/test/java/org/bukkit/TestServer.java @@ -1,100 +1,100 @@ -package org.bukkit;
-
-import java.lang.reflect.InvocationHandler;
-import java.lang.reflect.Method;
-import java.lang.reflect.Proxy;
-import java.util.Map;
-import java.util.logging.Logger;
-
-import org.bukkit.command.SimpleCommandMap;
-import org.bukkit.plugin.PluginManager;
-import org.bukkit.plugin.SimplePluginManager;
-
-import com.google.common.collect.ImmutableMap;
-
-public class TestServer implements InvocationHandler {
- private static interface MethodHandler {
- Object handle(TestServer server, Object[] args);
- }
-
- private static final Map<Method, MethodHandler> methods;
-
- static {
- try {
- ImmutableMap.Builder<Method, MethodHandler> methodMap = ImmutableMap.builder();
- methodMap.put(
- Server.class.getMethod("isPrimaryThread"),
- new MethodHandler() {
- public Object handle(TestServer server, Object[] args) {
- return Thread.currentThread().equals(server.creatingThread);
- }
- }
- );
- methodMap.put(
- Server.class.getMethod("getPluginManager"),
- new MethodHandler() {
- public Object handle(TestServer server, Object[] args) {
- return server.pluginManager;
- }
- }
- );
- methodMap.put(
- Server.class.getMethod("getLogger"),
- new MethodHandler() {
- final Logger logger = Logger.getLogger(TestServer.class.getCanonicalName());
- public Object handle(TestServer server, Object[] args) {
- return logger;
- }
- }
- );
- methodMap.put(
- Server.class.getMethod("getName"),
- new MethodHandler() {
- public Object handle(TestServer server, Object[] args) {
- return TestServer.class.getSimpleName();
- }
- }
- );
- methodMap.put(
- Server.class.getMethod("getVersion"),
- new MethodHandler() {
- public Object handle(TestServer server, Object[] args) {
- return "Version_" + TestServer.class.getPackage().getImplementationVersion();
- }
- }
- );
- methodMap.put(
- Server.class.getMethod("getBukkitVersion"),
- new MethodHandler() {
- public Object handle(TestServer server, Object[] args) {
- return "BukkitVersion_" + TestServer.class.getPackage().getImplementationVersion();
- }
- }
- );
- methods = methodMap.build();
-
- TestServer server = new TestServer();
- Server instance = Proxy.getProxyClass(Server.class.getClassLoader(), Server.class).asSubclass(Server.class).getConstructor(InvocationHandler.class).newInstance(server);
- Bukkit.setServer(instance);
- server.pluginManager = new SimplePluginManager(instance, new SimpleCommandMap(instance));
- } catch (Throwable t) {
- throw new Error(t);
- }
- }
-
- private Thread creatingThread = Thread.currentThread();
- private PluginManager pluginManager;
- private TestServer() {};
-
- public static Server getInstance() {
- return Bukkit.getServer();
- }
-
- public Object invoke(Object proxy, Method method, Object[] args) {
- MethodHandler handler = methods.get(method);
- if (handler != null) {
- return handler.handle(this, args);
- }
- throw new UnsupportedOperationException(String.valueOf(method));
- }
-}
+package org.bukkit; + +import java.lang.reflect.InvocationHandler; +import java.lang.reflect.Method; +import java.lang.reflect.Proxy; +import java.util.Map; +import java.util.logging.Logger; + +import org.bukkit.command.SimpleCommandMap; +import org.bukkit.plugin.PluginManager; +import org.bukkit.plugin.SimplePluginManager; + +import com.google.common.collect.ImmutableMap; + +public class TestServer implements InvocationHandler { + private static interface MethodHandler { + Object handle(TestServer server, Object[] args); + } + + private static final Map<Method, MethodHandler> methods; + + static { + try { + ImmutableMap.Builder<Method, MethodHandler> methodMap = ImmutableMap.builder(); + methodMap.put( + Server.class.getMethod("isPrimaryThread"), + new MethodHandler() { + public Object handle(TestServer server, Object[] args) { + return Thread.currentThread().equals(server.creatingThread); + } + } + ); + methodMap.put( + Server.class.getMethod("getPluginManager"), + new MethodHandler() { + public Object handle(TestServer server, Object[] args) { + return server.pluginManager; + } + } + ); + methodMap.put( + Server.class.getMethod("getLogger"), + new MethodHandler() { + final Logger logger = Logger.getLogger(TestServer.class.getCanonicalName()); + public Object handle(TestServer server, Object[] args) { + return logger; + } + } + ); + methodMap.put( + Server.class.getMethod("getName"), + new MethodHandler() { + public Object handle(TestServer server, Object[] args) { + return TestServer.class.getSimpleName(); + } + } + ); + methodMap.put( + Server.class.getMethod("getVersion"), + new MethodHandler() { + public Object handle(TestServer server, Object[] args) { + return "Version_" + TestServer.class.getPackage().getImplementationVersion(); + } + } + ); + methodMap.put( + Server.class.getMethod("getBukkitVersion"), + new MethodHandler() { + public Object handle(TestServer server, Object[] args) { + return "BukkitVersion_" + TestServer.class.getPackage().getImplementationVersion(); + } + } + ); + methods = methodMap.build(); + + TestServer server = new TestServer(); + Server instance = Proxy.getProxyClass(Server.class.getClassLoader(), Server.class).asSubclass(Server.class).getConstructor(InvocationHandler.class).newInstance(server); + Bukkit.setServer(instance); + server.pluginManager = new SimplePluginManager(instance, new SimpleCommandMap(instance)); + } catch (Throwable t) { + throw new Error(t); + } + } + + private Thread creatingThread = Thread.currentThread(); + private PluginManager pluginManager; + private TestServer() {}; + + public static Server getInstance() { + return Bukkit.getServer(); + } + + public Object invoke(Object proxy, Method method, Object[] args) { + MethodHandler handler = methods.get(method); + if (handler != null) { + return handler.handle(this, args); + } + throw new UnsupportedOperationException(String.valueOf(method)); + } +} diff --git a/src/test/java/org/bukkit/event/TestEvent.java b/src/test/java/org/bukkit/event/TestEvent.java index c06dfe94..25904f5f 100644 --- a/src/test/java/org/bukkit/event/TestEvent.java +++ b/src/test/java/org/bukkit/event/TestEvent.java @@ -1,19 +1,19 @@ -package org.bukkit.event;
-
-
-public class TestEvent extends Event {
- private static final HandlerList handlers = new HandlerList();
-
- public TestEvent(boolean async) {
- super(async);
- }
-
- @Override
- public HandlerList getHandlers() {
- return handlers;
- }
-
- public static HandlerList getHandlerList() {
- return handlers;
- }
-}
+package org.bukkit.event; + + +public class TestEvent extends Event { + private static final HandlerList handlers = new HandlerList(); + + public TestEvent(boolean async) { + super(async); + } + + @Override + public HandlerList getHandlers() { + return handlers; + } + + public static HandlerList getHandlerList() { + return handlers; + } +} diff --git a/src/test/java/org/bukkit/plugin/PluginManagerTest.java b/src/test/java/org/bukkit/plugin/PluginManagerTest.java index c4a240ee..6b86128e 100644 --- a/src/test/java/org/bukkit/plugin/PluginManagerTest.java +++ b/src/test/java/org/bukkit/plugin/PluginManagerTest.java @@ -1,170 +1,176 @@ -package org.bukkit.plugin;
-
-import static org.hamcrest.Matchers.*;
-import static org.junit.Assert.*;
-
-import org.bukkit.TestServer;
-import org.bukkit.event.Event;
-import org.bukkit.event.TestEvent;
-import org.bukkit.permissions.Permission;
-
-import org.junit.After;
-import org.junit.Test;
-
-public class PluginManagerTest {
- private class MutableObject {
- volatile Object value = null;
- }
-
- private static final PluginManager pm = TestServer.getInstance().getPluginManager();
-
- private final MutableObject store = new MutableObject();
-
- @Test
- public void testAsyncSameThread() {
- final Event event = new TestEvent(true);
- try {
- pm.callEvent(event);
- } catch (IllegalStateException ex) {
- assertThat(event.getEventName() + " cannot be triggered asynchronously from primary server thread.", is(ex.getMessage()));
- return;
- }
- throw new IllegalStateException("No exception thrown");
- }
-
- @Test
- public void testSyncSameThread() {
- final Event event = new TestEvent(false);
- pm.callEvent(event);
- }
-
- @Test
- public void testAsyncLocked() throws InterruptedException {
- final Event event = new TestEvent(true);
- Thread secondThread = new Thread(
- new Runnable() {
- public void run() {
- try {
- synchronized (pm) {
- pm.callEvent(event);
- }
- } catch (Throwable ex) {
- store.value = ex;
- }
- }});
- secondThread.start();
- secondThread.join();
- assertThat(store.value, is(instanceOf(IllegalStateException.class)));
- assertThat(event.getEventName() + " cannot be triggered asynchronously from inside synchronized code.", is(((Throwable) store.value).getMessage()));
- }
-
- @Test
- public void testAsyncUnlocked() throws InterruptedException {
- final Event event = new TestEvent(true);
- Thread secondThread = new Thread(
- new Runnable() {
- public void run() {
- try {
- pm.callEvent(event);
- } catch (Throwable ex) {
- store.value = ex;
- }
- }});
- secondThread.start();
- secondThread.join();
- if (store.value != null) {
- throw new RuntimeException((Throwable) store.value);
- }
- }
-
- @Test
- public void testSyncUnlocked() throws InterruptedException {
- final Event event = new TestEvent(false);
- Thread secondThread = new Thread(
- new Runnable() {
- public void run() {
- try {
- pm.callEvent(event);
- } catch (Throwable ex) {
- store.value = ex;
- }
- }});
- secondThread.start();
- secondThread.join();
- if (store.value != null) {
- throw new RuntimeException((Throwable) store.value);
- }
- }
-
- @Test
- public void testSyncLocked() throws InterruptedException {
- final Event event = new TestEvent(false);
- Thread secondThread = new Thread(
- new Runnable() {
- public void run() {
- try {
- synchronized (pm) {
- pm.callEvent(event);
- }
- } catch (Throwable ex) {
- store.value = ex;
- }
- }});
- secondThread.start();
- secondThread.join();
- if (store.value != null) {
- throw new RuntimeException((Throwable) store.value);
- }
- }
-
- @Test
- public void testRemovePermissionByNameLower() {
- this.testRemovePermissionByName("lower");
- }
-
- @Test
- public void testRemovePermissionByNameUpper() {
- this.testRemovePermissionByName("UPPER");
- }
-
- @Test
- public void testRemovePermissionByNameCamel() {
- this.testRemovePermissionByName("CaMeL");
- }
-
- public void testRemovePermissionByPermissionLower() {
- this.testRemovePermissionByPermission("lower");
- }
-
- @Test
- public void testRemovePermissionByPermissionUpper() {
- this.testRemovePermissionByPermission("UPPER");
- }
-
- @Test
- public void testRemovePermissionByPermissionCamel() {
- this.testRemovePermissionByPermission("CaMeL");
- }
-
- private void testRemovePermissionByName(final String name) {
- final Permission perm = new Permission(name);
- pm.addPermission(perm);
- assertThat("Permission \"" + name + "\" was not added", pm.getPermission(name), is(perm));
- pm.removePermission(name);
- assertThat("Permission \"" + name + "\" was not removed", pm.getPermission(name), is(nullValue()));
- }
-
- private void testRemovePermissionByPermission(final String name) {
- final Permission perm = new Permission(name);
- pm.addPermission(perm);
- assertThat("Permission \"" + name + "\" was not added", pm.getPermission(name), is(perm));
- pm.removePermission(perm);
- assertThat("Permission \"" + name + "\" was not removed", pm.getPermission(name), is(nullValue()));
- }
-
- @After
- public void tearDown() {
- pm.clearPlugins();
- assertThat(pm.getPermissions(), is(empty()));
- }
-}
+package org.bukkit.plugin; + +import static org.hamcrest.Matchers.*; +import static org.junit.Assert.*; + +import org.bukkit.TestServer; +import org.bukkit.event.Event; +import org.bukkit.event.TestEvent; +import org.bukkit.permissions.Permission; + +import org.junit.After; +import org.junit.Test; + +public class PluginManagerTest { + private class MutableObject { + volatile Object value = null; + } + + private static final PluginManager pm = TestServer.getInstance().getPluginManager(); + + private final MutableObject store = new MutableObject(); + + @Test + public void testAsyncSameThread() { + final Event event = new TestEvent(true); + try { + pm.callEvent(event); + } catch (IllegalStateException ex) { + assertThat(event.getEventName() + " cannot be triggered asynchronously from primary server thread.", is(ex.getMessage())); + return; + } + throw new IllegalStateException("No exception thrown"); + } + + @Test + public void testSyncSameThread() { + final Event event = new TestEvent(false); + pm.callEvent(event); + } + + @Test + public void testAsyncLocked() throws InterruptedException { + final Event event = new TestEvent(true); + Thread secondThread = new Thread( + new Runnable() { + public void run() { + try { + synchronized (pm) { + pm.callEvent(event); + } + } catch (Throwable ex) { + store.value = ex; + } + } + } + ); + secondThread.start(); + secondThread.join(); + assertThat(store.value, is(instanceOf(IllegalStateException.class))); + assertThat(event.getEventName() + " cannot be triggered asynchronously from inside synchronized code.", is(((Throwable) store.value).getMessage())); + } + + @Test + public void testAsyncUnlocked() throws InterruptedException { + final Event event = new TestEvent(true); + Thread secondThread = new Thread( + new Runnable() { + public void run() { + try { + pm.callEvent(event); + } catch (Throwable ex) { + store.value = ex; + } + }}); + secondThread.start(); + secondThread.join(); + if (store.value != null) { + throw new RuntimeException((Throwable) store.value); + } + } + + @Test + public void testSyncUnlocked() throws InterruptedException { + final Event event = new TestEvent(false); + Thread secondThread = new Thread( + new Runnable() { + public void run() { + try { + pm.callEvent(event); + } catch (Throwable ex) { + store.value = ex; + } + } + } + ); + secondThread.start(); + secondThread.join(); + if (store.value != null) { + throw new RuntimeException((Throwable) store.value); + } + } + + @Test + public void testSyncLocked() throws InterruptedException { + final Event event = new TestEvent(false); + Thread secondThread = new Thread( + new Runnable() { + public void run() { + try { + synchronized (pm) { + pm.callEvent(event); + } + } catch (Throwable ex) { + store.value = ex; + } + } + } + ); + secondThread.start(); + secondThread.join(); + if (store.value != null) { + throw new RuntimeException((Throwable) store.value); + } + } + + @Test + public void testRemovePermissionByNameLower() { + this.testRemovePermissionByName("lower"); + } + + @Test + public void testRemovePermissionByNameUpper() { + this.testRemovePermissionByName("UPPER"); + } + + @Test + public void testRemovePermissionByNameCamel() { + this.testRemovePermissionByName("CaMeL"); + } + + public void testRemovePermissionByPermissionLower() { + this.testRemovePermissionByPermission("lower"); + } + + @Test + public void testRemovePermissionByPermissionUpper() { + this.testRemovePermissionByPermission("UPPER"); + } + + @Test + public void testRemovePermissionByPermissionCamel() { + this.testRemovePermissionByPermission("CaMeL"); + } + + private void testRemovePermissionByName(final String name) { + final Permission perm = new Permission(name); + pm.addPermission(perm); + assertThat("Permission \"" + name + "\" was not added", pm.getPermission(name), is(perm)); + pm.removePermission(name); + assertThat("Permission \"" + name + "\" was not removed", pm.getPermission(name), is(nullValue())); + } + + private void testRemovePermissionByPermission(final String name) { + final Permission perm = new Permission(name); + pm.addPermission(perm); + assertThat("Permission \"" + name + "\" was not added", pm.getPermission(name), is(perm)); + pm.removePermission(perm); + assertThat("Permission \"" + name + "\" was not removed", pm.getPermission(name), is(nullValue())); + } + + @After + public void tearDown() { + pm.clearPlugins(); + assertThat(pm.getPermissions(), is(empty())); + } +} |