new javadoc for Vector2f (#1729)

* Vector2f:  javadoc improvements

* Vector2f:  javadoc tweaks

jme3-core/src/main/java/com/jme3/math/Vector2f.java

@@ -38,7 +38,11 @@ import java.io.ObjectOutput;
 import java.util.logging.Logger;
 
 /**
- * <code>Vector2f</code> defines a Vector for a two float value vector.
+ * A vector composed of 2 single-precision components, used to represent
+ * locations, offsets, directions, and rotations in 2-dimensional space.
+ *
+ * <p>Methods with names ending in "Local" modify the current instance. They are
+ * used to avoid creating garbage.
  *
  * @author Mark Powell
  * @author Joshua Slack
@@ -47,27 +51,27 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     static final long serialVersionUID = 1;
     private static final Logger logger = Logger.getLogger(Vector2f.class.getName());
     /**
-     * shared instance of the all-zero vector (0,0) - Do not modify!
+     * Shared instance of the all-zero vector (0,0). Do not modify!
      */
     public static final Vector2f ZERO = new Vector2f(0f, 0f);
     /**
-     * shared instance of the all-ones vector (1,1) - Do not modify!
+     * Shared instance of the all-ones vector (1,1). Do not modify!
      */
     public static final Vector2f UNIT_XY = new Vector2f(1f, 1f);
     /**
-     * the x value of the vector.
+     * The first (X) component.
      */
     public float x;
     /**
-     * the y value of the vector.
+     * The 2nd (Y) component.
      */
     public float y;
 
     /**
-     * Creates a Vector2f with the given initial x and y values.
+     * Instantiates a vector with specified components.
      *
-     * @param x   The x value of this Vector2f.
-     * @param y   The y value of this Vector2f.
+     * @param x the desired X component
+     * @param y the desired Y component
      */
     public Vector2f(float x, float y) {
         this.x = x;
@@ -75,17 +79,16 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Creates a Vector2f with x and y set to 0. Equivalent to Vector2f(0,0).
+     * Instantiates an all-zero vector (0,0).
      */
     public Vector2f() {
         x = y = 0;
     }
 
     /**
-     * Creates a new Vector2f that contains the passed vector's information
+     * Instantiates a copy of the argument.
      *
-     * @param vector2f
-     *            The vector to copy
+     * @param vector2f the vector to copy (not null, unaffected)
      */
     public Vector2f(Vector2f vector2f) {
         this.x = vector2f.x;
@@ -93,11 +96,11 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * set the x and y values of the vector
+     * Sets both components to specified values.
      *
-     * @param x   the x value of the vector.
-     * @param y   the y value of the vector.
-     * @return this vector
+     * @param x the desired X component
+     * @param y the desired Y component
+     * @return the (modified) current instance (for chaining)
      */
     public Vector2f set(float x, float y) {
         this.x = x;
@@ -106,11 +109,10 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * set the x and y values of the vector from another vector
+     * Copies both components from the argument.
      *
-     * @param vec
-     *            the vector to copy from
-     * @return this vector
+     * @param vec the Vector2f to copy (not null, unaffected)
+     * @return the (modified) current instance (for chaining)
      */
     public Vector2f set(Vector2f vec) {
         this.x = vec.x;
@@ -119,13 +121,12 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>add</code> adds a provided vector to this vector creating a
-     * resultant vector which is returned. If the provided vector is null, null
-     * is returned.
+     * Adds the argument and returns the sum as a new instance. If the argument
+     * is null, null is returned. Either way, the current instance is
+     * unaffected.
      *
-     * @param vec
-     *            the vector to add to this.
-     * @return the resultant vector.
+     * @param vec the vector to add (unaffected) or null for none
+     * @return a new Vector2f or null
      */
     public Vector2f add(Vector2f vec) {
         if (null == vec) {
@@ -136,13 +137,12 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>addLocal</code> adds a provided vector to this vector internally,
-     * and returns a handle to this vector for easy chaining of calls. If the
-     * provided vector is null, null is returned.
+     * Adds the argument and returns the (modified) current instance. If the
+     * argument is null, null is returned.
      *
-     * @param vec
-     *            the vector to add to this vector.
-     * @return this
+     * @param vec the vector to add (unaffected unless it's {@code this}) or
+     *     null for none
+     * @return the (modified) current instance or null
      */
     public Vector2f addLocal(Vector2f vec) {
         if (null == vec) {
@@ -155,15 +155,12 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>addLocal</code> adds the provided values to this vector
-     * internally, and returns a handle to this vector for easy chaining of
-     * calls.
+     * Adds specified amounts to the vector's components and returns the
+     * (modified) current instance.
      *
-     * @param addX
-     *            value to add to x
-     * @param addY
-     *            value to add to y
-     * @return this
+     * @param addX the amount to add to the X component
+     * @param addY the amount to add to the Y component
+     * @return the (modified) current instance (for chaining)
      */
     public Vector2f addLocal(float addX, float addY) {
         x += addX;
@@ -172,14 +169,14 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>add</code> adds this vector by <code>vec</code> and stores the
-     * result in <code>result</code>.
+     * Adds a specified vector and returns the sum in a 3rd vector. If the
+     * argument is null, null is returned. Either way, the current instance is
+     * unaffected unless it's {@code result}.
      *
-     * @param vec
-     *            The vector to add.
-     * @param result
-     *            The vector to store the result in.
-     * @return The result vector, after adding.
+     * @param vec the vector to add (unaffected unless it's {@code result}) or
+     *     null for none
+     * @param result storage for the sum, or null for a new Vector2f
+     * @return the sum (either {@code result} or a new Vector2f)
      */
     public Vector2f add(Vector2f vec, Vector2f result) {
         if (null == vec) {
@@ -195,12 +192,11 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>dot</code> calculates the dot product of this vector with a
-     * provided vector. If the provided vector is null, 0 is returned.
+     * Returns the dot (or inner) product with the argument. If the argument is
+     * null, 0 is returned. Either way, the current instance is unaffected.
      *
-     * @param vec
-     *            the vector to dot with this vector.
-     * @return the resultant dot product of this vector and a given vector.
+     * @param vec the vector to multiply (unaffected) or null for none
+     * @return the product or 0
      */
     public float dot(Vector2f vec) {
         if (null == vec) {
@@ -211,30 +207,37 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>cross</code> calculates the cross product of this vector with a
-     * parameter vector v.
+     * Calculates a cross product with the argument and returns the product as a
+     * new instance. The current instance is unaffected.
      *
-     * @param v   the vector to take the cross product of with this.
-     * @return the cross product vector.
+     * @param v the right factor (not null, unaffected)
+     * @return {@code this} cross {@code v} (a new Vector3f)
      */
     public Vector3f cross(Vector2f v) {
         return new Vector3f(0, 0, determinant(v));
     }
 
+    /**
+     * Returns the Z component of the cross product with the argument. The
+     * current instance is unaffected.
+     *
+     * @param v the right factor (not null, unaffected)
+     * @return the Z component of {@code this} cross {@code v}
+     */
     public float determinant(Vector2f v) {
         return (x * v.y) - (y * v.x);
     }
 
     /**
-     * Sets this vector to the interpolation by changeAmount from this to the
-     * finalVec this=(1-changeAmount)*this + changeAmount * finalVec
+     * Interpolates linearly between the current instance and the specified
+     * vector, returning the (modified) current instance.
+     *
+     * <p>this = (1 - changeAmount) * this + changeAmount * finalVec
      *
-     * @param finalVec
-     *            The final vector to interpolate towards
-     * @param changeAmount
-     *            An amount between 0.0 - 1.0 representing a percentage change
-     *            from this towards finalVec
-     * @return this
+     * @param finalVec the desired value when changeAmount=1 (not null,
+     *     unaffected unless it's {@code this})
+     * @param changeAmount the fractional change amount
+     * @return the (modified) current instance (for chaining)
      */
     public Vector2f interpolateLocal(Vector2f finalVec, float changeAmount) {
         this.x = (1 - changeAmount) * this.x + changeAmount * finalVec.x;
@@ -243,17 +246,17 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Sets this vector to the interpolation by changeAmount from beginVec to
-     * finalVec this=(1-changeAmount)*beginVec + changeAmount * finalVec
+     * Interpolates linearly between the specified beginning and final vectors,
+     * returning the (modified) current instance.
+     *
+     * <p>this = (1 - changeAmount) * beginVec + changeAmount * finalVec
      *
-     * @param beginVec
-     *            The beginning vector (delta=0)
-     * @param finalVec
-     *            The final vector to interpolate towards (delta=1)
-     * @param changeAmount
-     *            An amount between 0.0 - 1.0 representing a percentage change
-     *            from beginVec towards finalVec
-     * @return this
+     * @param beginVec the desired value when changeAmount=0 (not null,
+     *     unaffected unless it's {@code this})
+     * @param finalVec the desired value when changeAmount=1 (not null,
+     *     unaffected unless it's {@code this})
+     * @param changeAmount the fractional change amount
+     * @return the (modified) current instance (for chaining)
      */
     public Vector2f interpolateLocal(Vector2f beginVec, Vector2f finalVec,
             float changeAmount) {
@@ -263,12 +266,11 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Check a vector... if it is null or its floats are NaN or infinite, return
-     * false. Else return true.
+     * Tests whether the argument is a valid vector, returning false if it's
+     * null or if any component is NaN or infinite.
      *
-     * @param vector
-     *            the vector to check
-     * @return true or false as stated above.
+     * @param vector the vector to test (unaffected)
+     * @return true if non-null and finite, otherwise false
      */
     public static boolean isValidVector(Vector2f vector) {
         if (vector == null) {
@@ -286,30 +288,29 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>length</code> calculates the magnitude of this vector.
+     * Returns the length (or magnitude). The current instance is unaffected.
      *
-     * @return the length or magnitude of the vector.
+     * @return the root-sum of the squared components (not negative)
      */
     public float length() {
         return FastMath.sqrt(lengthSquared());
     }
 
     /**
-     * <code>lengthSquared</code> calculates the squared value of the
-     * magnitude of the vector.
+     * Returns the square of the length. The current instance is unaffected.
      *
-     * @return the magnitude squared of the vector.
+     * @return the sum of the squared components (not negative)
      */
     public float lengthSquared() {
         return x * x + y * y;
     }
 
     /**
-     * <code>distanceSquared</code> calculates the distance squared between
-     * this vector and vector v.
+     * Returns the square of the distance between the current instance and the
+     * argument. The current instance is unaffected.
      *
-     * @param v the second vector to determine the distance squared.
-     * @return the distance squared between the two vectors.
+     * @param v the vector to compare (not null, unaffected)
+     * @return the square of the Euclidean distance (not negative)
      */
     public float distanceSquared(Vector2f v) {
         double dx = x - v.x;
@@ -318,12 +319,12 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>distanceSquared</code> calculates the distance squared between
-     * this vector and vector v.
+     * Returns the square of the distance between the current instance and a
+     * vector with the specified components. The current instance is unaffected.
      *
-     * @param otherX The X coordinate of the v vector
-     * @param otherY The Y coordinate of the v vector
-     * @return the distance squared between the two vectors.
+     * @param otherX the X component of the vector to compare
+     * @param otherY the Y component of the vector to compare
+     * @return the square of the Euclidean distance (not negative)
      */
     public float distanceSquared(float otherX, float otherY) {
         double dx = x - otherX;
@@ -332,35 +333,33 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>distance</code> calculates the distance between this vector and
-     * vector v.
+     * Returns the distance between the current instance and the argument. The
+     * current instance is unaffected.
      *
-     * @param v the second vector to determine the distance.
-     * @return the distance between the two vectors.
+     * @param v the vector to compare (not null, unaffected)
+     * @return the Euclidean distance (not negative)
      */
     public float distance(Vector2f v) {
         return FastMath.sqrt(distanceSquared(v));
     }
 
     /**
-     * <code>mult</code> multiplies this vector by a scalar. The resultant
-     * vector is returned.
+     * Multiplies with the scalar argument and returns the product as a new
+     * instance. The current instance is unaffected.
      *
-     * @param scalar
-     *            the value to multiply this vector by.
-     * @return the new vector.
+     * @param scalar the scaling factor
+     * @return a new {@code Vector2f}
      */
     public Vector2f mult(float scalar) {
         return new Vector2f(x * scalar, y * scalar);
     }
 
     /**
-     * <code>multLocal</code> multiplies this vector by a scalar internally,
-     * and returns a handle to this vector for easy chaining of calls.
+     * Multiplies by the scalar argument and returns the (modified) current
+     * instance.
      *
-     * @param scalar
-     *            the value to multiply this vector by.
-     * @return this
+     * @param scalar the scaling factor
+     * @return the (modified) current instance (for chaining)
      */
     public Vector2f multLocal(float scalar) {
         x *= scalar;
@@ -369,13 +368,12 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>multLocal</code> multiplies a provided vector by this vector
-     * internally, and returns a handle to this vector for easy chaining of
-     * calls. If the provided vector is null, null is returned.
+     * Multiplies component-wise by the argument and returns the (modified)
+     * current instance. If the argument is null, null is returned.
      *
-     * @param vec
-     *            the vector to mult to this vector.
-     * @return this
+     * @param vec the scale vector (unaffected unless it's {@code this}) or
+     *     null for none
+     * @return the (modified) current instance (for chaining) or null
      */
     public Vector2f multLocal(Vector2f vec) {
         if (null == vec) {
@@ -388,15 +386,12 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Multiplies this Vector2f's x and y by the scalar and stores the result in
-     * product. The result is returned for chaining. Similar to
-     * product=this*scalar;
+     * Multiplies with the specified scalar and stores the product in the
+     * specified vector. The current instance is unaffected.
      *
-     * @param scalar
-     *            The scalar to multiply by.
-     * @param product
-     *            The vector2f to store the result in.
-     * @return product, after multiplication.
+     * @param scalar the scaling factor
+     * @param product storage for the product, or null for a new Vector2f
+     * @return either {@code product} or a new Vector2f
      */
     public Vector2f mult(float scalar, Vector2f product) {
         if (null == product) {
@@ -409,25 +404,22 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>divide</code> divides the values of this vector by a scalar and
-     * returns the result. The values of this vector remain untouched.
+     * Divides by the scalar argument and returns the quotient as a new
+     * instance. The current instance is unaffected.
      *
-     * @param scalar
-     *            the value to divide this vectors attributes by.
-     * @return the result <code>Vector</code>.
+     * @param scalar the divisor
+     * @return a new {@code Vector2f}
      */
     public Vector2f divide(float scalar) {
         return new Vector2f(x / scalar, y / scalar);
     }
 
     /**
-     * <code>divideLocal</code> divides this vector by a scalar internally,
-     * and returns a handle to this vector for easy chaining of calls. Dividing
-     * by zero will result in an exception.
+     * Divides the vector by the scalar argument and returns the (modified)
+     * current instance.
      *
-     * @param scalar
-     *            the value to divides this vector by.
-     * @return this
+     * @param scalar the divisor
+     * @return the (modified) current instance (for chaining)
      */
     public Vector2f divideLocal(float scalar) {
         x /= scalar;
@@ -436,19 +428,18 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>negate</code> returns the negative of this vector. All values are
-     * negated and set to a new vector.
+     * Returns the negative of the vector. The current instance is unaffected.
      *
-     * @return the negated vector.
+     * @return a new Vector2f
      */
     public Vector2f negate() {
         return new Vector2f(-x, -y);
     }
 
     /**
-     * <code>negateLocal</code> negates the internal values of this vector.
+     * Negates both components and returns the (modified) current instance.
      *
-     * @return this.
+     * @return the (modified) current instance (for chaining)
      */
     public Vector2f negateLocal() {
         x = -x;
@@ -457,29 +448,26 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>subtract</code> subtracts the values of a given vector from those
-     * of this vector creating a new vector object. If the provided vector is
-     * null, an exception is thrown.
+     * Subtracts the argument and returns the difference as a new instance. The
+     * current instance is unaffected.
      *
-     * @param vec
-     *            the vector to subtract from this vector.
-     * @return the result vector.
+     * @param vec the vector to subtract (not null, unaffected)
+     * @return a new Vector2f
      */
     public Vector2f subtract(Vector2f vec) {
         return subtract(vec, null);
     }
 
     /**
-     * <code>subtract</code> subtracts the values of a given vector from those
-     * of this vector storing the result in the given vector object. If the
-     * provided vector is null, an exception is thrown.
+     * Subtracts the specified vector and returns the difference in a 3rd
+     * vector. The current instance is unaffected unless it's {@code store}.
      *
-     * @param vec
-     *            the vector to subtract from this vector.
-     * @param store
-     *            the vector to store the result in. It is safe for this to be
-     *            the same as vec. If null, a new vector is created.
-     * @return the result vector.
+     * <p>It is safe for {@code vec} and {@code store} to be the same object.
+     *
+     * @param vec the vector to subtract (not null, unaffected unless it's
+     *     {@code store})
+     * @param store storage for the difference, or null for a new Vector2f
+     * @return either {@code store} or a new Vector2f
      */
     public Vector2f subtract(Vector2f vec, Vector2f store) {
         if (store == null) {
@@ -491,27 +479,24 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>subtract</code> subtracts the given x,y values from those of this
-     * vector creating a new vector object.
+     * Subtracts the specified amounts from the vector's components and returns
+     * the difference as a new instance. The current instance is unaffected.
      *
-     * @param valX
-     *            value to subtract from x
-     * @param valY
-     *            value to subtract from y
-     * @return this
+     * @param valX the amount to subtract from the X component
+     * @param valY the amount to subtract from the Y component
+     * @return a new Vector2f
      */
     public Vector2f subtract(float valX, float valY) {
         return new Vector2f(x - valX, y - valY);
     }
 
     /**
-     * <code>subtractLocal</code> subtracts a provided vector to this vector
-     * internally, and returns a handle to this vector for easy chaining of
-     * calls. If the provided vector is null, null is returned.
+     * Subtracts the argument and returns the (modified) current instance. If
+     * the argument is null, null is returned.
      *
-     * @param vec
-     *            the vector to subtract
-     * @return this
+     * @param vec the vector to subtract (unaffected unless it's {@code this})
+     *     or null for none
+     * @return the (modified) current instance or null
      */
     public Vector2f subtractLocal(Vector2f vec) {
         if (null == vec) {
@@ -524,15 +509,12 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>subtractLocal</code> subtracts the provided values from this
-     * vector internally, and returns a handle to this vector for easy chaining
-     * of calls.
+     * Subtracts the specified amounts from the vector's components and returns
+     * the (modified) current instance.
      *
-     * @param valX
-     *            value to subtract from x
-     * @param valY
-     *            value to subtract from y
-     * @return this
+     * @param valX the amount to subtract from the X component
+     * @param valY the amount to subtract from the Y component
+     * @return the (modified) current instance (for chaining)
      */
     public Vector2f subtractLocal(float valX, float valY) {
         x -= valX;
@@ -541,9 +523,11 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>normalize</code> returns the unit vector of this vector.
+     * Normalizes the vector to length=1 and returns the result as a new
+     * instance. If the vector has length=0, a clone is returned. Either way,
+     * the current instance is unaffected.
      *
-     * @return unit vector of this vector.
+     * @return a new Vector2f
      */
     public Vector2f normalize() {
         float length = length();
@@ -555,10 +539,10 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>normalizeLocal</code> makes this vector into a unit vector of
-     * itself.
+     * Normalizes the vector to length=1 and returns the (modified) current
+     * instance. If the vector has length=0, it's unchanged.
      *
-     * @return this.
+     * @return the (modified) current instance (for chaining)
      */
     public Vector2f normalizeLocal() {
         float length = length();
@@ -570,13 +554,13 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>smallestAngleBetween</code> returns (in radians) the minimum
-     * angle between two vectors. It is assumed that both this vector and the
-     * given vector are unit vectors (iow, normalized).
+     * Returns the unsigned angle between the current instance and the argument,
+     * provided both vectors have length=1. If {@code otherVector} is null, Pi/2
+     * is returned. The current instance is unaffected.
      *
-     * @param otherVector
-     *            a unit vector to find the angle against
-     * @return the angle in radians.
+     * @param otherVector the unit vector to compare (unaffected) or null for
+     *     none
+     * @return the angle in radians (not negative)
      */
     public float smallestAngleBetween(Vector2f otherVector) {
         float dotProduct = dot(otherVector);
@@ -585,14 +569,12 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>angleBetween</code> returns (in radians) the angle required to
-     * rotate a ray represented by this vector to be collinear with a ray
-     * described by the given vector. It is assumed that both this vector and
-     * the given vector are unit vectors (iow, normalized).
+     * Returns the signed angle between the current instance and the argument.
+     * The current instance is unaffected.
      *
-     * @param otherVector
-     *            the "destination" unit vector
-     * @return the angle in radians.
+     * @param otherVector the vector to compare (not null, unaffected)
+     * @return the angle in radians, measured counter-clockwise from {@code
+     *     this} to {@code otherVector} (&ge;-2*Pi, &le;2*Pi)
      */
     public float angleBetween(Vector2f otherVector) {
         float angle = FastMath.atan2(otherVector.y, otherVector.x)
@@ -601,19 +583,19 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Determine the X component of this vector.
+     * Returns the X component. The vector is unaffected.
      *
-     * @return x
+     * @return the value of the {@link #x} component
      */
     public float getX() {
         return x;
     }
 
     /**
-     * Alter the X component of this vector.
+     * Sets the X component.
      *
      * @param x the desired value
-     * @return this vector, modified
+     * @return the (modified) current instance (for chaining)
      */
     public Vector2f setX(float x) {
         this.x = x;
@@ -621,19 +603,19 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Determine the Y component of this vector.
+     * Returns the Y component. The vector is unaffected.
      *
-     * @return y
+     * @return the value of the {@link #y} component
      */
     public float getY() {
         return y;
     }
 
     /**
-     * Alter the Y component of this vector.
+     * Sets the Y component.
      *
      * @param y the desired value
-     * @return this vector, modified
+     * @return the (modified) current instance (for chaining)
      */
     public Vector2f setY(float y) {
         this.y = y;
@@ -641,20 +623,20 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>getAngle</code> returns (in radians) the angle represented by
-     * this Vector2f as expressed by a conversion from rectangular coordinates (<code>x</code>,&nbsp;<code>y</code>)
-     * to polar coordinates (r,&nbsp;<i>theta</i>).
+     * Returns the angle of the vector in polar coordinates. The current
+     * instance is unaffected.
      *
-     * @return the angle in radians. [-pi, pi)
+     * @return the polar angle in radians, measured counter-clockwise from the
+     *     +X axis (&ge;-Pi, &le;Pi)
      */
     public float getAngle() {
         return FastMath.atan2(y, x);
     }
 
     /**
-     * <code>zero</code> resets this vector's data to zero internally.
+     * Sets both components to zero.
      *
-     * @return this
+     * @return the (modified) current instance (for chaining)
      */
     public Vector2f zero() {
         x = y = 0;
@@ -662,11 +644,10 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>hashCode</code> returns a unique code for this vector object
-     * based on its values. If two vectors are logically equivalent, they will
-     * return the same hash code value.
+     * Returns a hash code. If two vectors are logically equivalent, they will
+     * return the same hash code. The current instance is unaffected.
      *
-     * @return the hash code value of this vector.
+     * @return the hash code value
      */
     @Override
     public int hashCode() {
@@ -677,9 +658,9 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Create a copy of this vector.
+     * Creates a copy. The current instance is unaffected.
      *
-     * @return a new instance, equivalent to this one
+     * @return a new instance, equivalent to the current one
      */
     @Override
     public Vector2f clone() {
@@ -691,12 +672,13 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Saves this Vector2f into the given float[] object.
+     * Copies the vector to the array argument. The current instance is
+     * unaffected.
      *
-     * @param floats
-     *            The float[] to take this Vector2f. If null, a new float[2] is
-     *            created.
-     * @return The array, with X, Y float values in that order
+     * @param floats storage for the components (must have length&ge;2) or null
+     *     for a new float[2]
+     * @return an array containing the X and Y components in that order (either
+     *     {@code floats} or a new float[2])
      */
     public float[] toArray(float[] floats) {
         if (floats == null) {
@@ -708,11 +690,12 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Are these two vectors the same? They are if they have the same x and
-     * y values.
+     * Tests for exact equality with the argument, distinguishing -0 from 0. If
+     * {@code o} is null, false is returned. Either way, the current instance is
+     * unaffected.
      *
-     * @param o   the object to compare for equality
-     * @return true if they are equal
+     * @param o the object to compare (unaffected) or null for none
+     * @return true if equal, otherwise false
      */
     @Override
     public boolean equals(Object o) {
@@ -735,11 +718,12 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Returns true if this vector is similar to the specified vector within
-     * some value of epsilon.
+     * Tests for approximate equality with the specified vector, using the
+     * specified tolerance. If {@code other} is null, false is returned. Either
+     * way, the current instance is unaffected.
      *
-     * @param other the vector to compare with (not null, unaffected)
-     * @param epsilon the desired error tolerance for each component
+     * @param other the vector to compare (unaffected) or null for none
+     * @param epsilon the tolerance for each component
      * @return true if both components are within tolerance, otherwise false
      */
     public boolean isSimilar(Vector2f other, float epsilon) {
@@ -756,12 +740,12 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * <code>toString</code> returns a string representation of this vector.
-     * The format is:
+     * Returns a string representation of the vector. The current instance is
+     * unaffected. The format is:
      *
-     * (XX.XXXX, YY.YYYY)
+     * <p>(XX.XXXX, YY.YYYY)
      *
-     * @return the string representation of this vector.
+     * @return the string representation
      */
     @Override
     public String toString() {
@@ -769,12 +753,14 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Used with serialization. Not to be called manually.
+     * Sets the vector from an {@code ObjectInput} object.
+     *
+     * <p>Used with serialization. Shouldn't be invoked directly by application
+     * code.
      *
-     * @param in
-     *            ObjectInput
-     * @throws IOException if an I/O error occurs
-     * @throws ClassNotFoundException when?
+     * @param in the object to read from (not null)
+     * @throws IOException if the ObjectInput cannot read a float
+     * @throws ClassNotFoundException never
      * @see java.io.Externalizable
      */
     public void readExternal(ObjectInput in) throws IOException,
@@ -784,11 +770,14 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Used with serialization. Not to be called manually.
+     * Writes the vector to an {@code ObjectOutput} object. The current instance
+     * is unaffected.
+     *
+     * <p>Used with serialization. Shouldn't be invoked directly by application
+     * code.
      *
-     * @param out
-     *            ObjectOutput
-     * @throws IOException if an I/O error occurs
+     * @param out the object to write to (not null)
+     * @throws IOException if the ObjectOuput cannot write a float
      * @see java.io.Externalizable
      */
     public void writeExternal(ObjectOutput out) throws IOException {
@@ -797,10 +786,10 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * Serialize this vector to the specified exporter, for example when
-     * saving to a J3O file.
+     * Serializes the vector to the specified exporter, for example when saving
+     * to a J3O file. The current instance is unaffected.
      *
-     * @param e (not null)
+     * @param e the exporter to use (not null)
      * @throws IOException from the exporter
      */
     @Override
@@ -811,10 +800,10 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
     }
 
     /**
-     * De-serialize this vector from the specified importer, for example
+     * De-serializes the vector from the specified importer, for example
      * when loading from a J3O file.
      *
-     * @param importer (not null)
+     * @param importer the importer to use (not null)
      * @throws IOException from the importer
      */
     @Override
@@ -824,6 +813,12 @@ public final class Vector2f implements Savable, Cloneable, java.io.Serializable
         y = capsule.readFloat("y", 0);
     }
 
+    /**
+     * Rotates the vector around (0,0) by the specified angle.
+     *
+     * @param angle the rotation angle (in radians)
+     * @param cw true to rotate clockwise, false to rotate counter-clockwise
+     */
     public void rotateAroundOrigin(float angle, boolean cw) {
         if (cw) {
             angle = -angle;