Pulling all pending Bukkit-JavaDoc changes

A special thanks goes to @aerouk for almost all of the changes found here. By: Wesley Wolfe <weswolf@aol.com>
2013-12-15 01:07:43 -05:00
parent 800679913f
commit bb50f1a774
310 changed files with 4218 additions and 2904 deletions
--- a/paper-api/src/main/java/org/bukkit/util/BlockIterator.java
+++ b/paper-api/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) {
--- a/paper-api/src/main/java/org/bukkit/util/ChatPaginator.java
+++ b/paper-api/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.
--- a/paper-api/src/main/java/org/bukkit/util/StringUtil.java
+++ b/paper-api/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
     */
--- a/paper-api/src/main/java/org/bukkit/util/Vector.java
+++ b/paper-api/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.
     */
--- a/paper-api/src/main/java/org/bukkit/util/noise/NoiseGenerator.java
+++ b/paper-api/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
--- a/paper-api/src/main/java/org/bukkit/util/noise/OctaveGenerator.java
+++ b/paper-api/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
--- a/paper-api/src/main/java/org/bukkit/util/noise/PerlinNoiseGenerator.java
+++ b/paper-api/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
--- a/paper-api/src/main/java/org/bukkit/util/noise/PerlinOctaveGenerator.java
+++ b/paper-api/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
     *
--- a/paper-api/src/main/java/org/bukkit/util/noise/SimplexNoiseGenerator.java
+++ b/paper-api/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
--- a/paper-api/src/main/java/org/bukkit/util/noise/SimplexOctaveGenerator.java
+++ b/paper-api/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