Minor modifications in documentation of vectors.

2 files changed, 43 insertions, 30 deletions

diff --git a/src/main/scala/sims/math/PseudoVector3D.scala b/src/main/scala/sims/math/PseudoVector3D.scala
index ea51c10..282cc70 100644
--- a/src/main/scala/sims/math/PseudoVector3D.scala
+++ b/src/main/scala/sims/math/PseudoVector3D.scala
@@ -7,10 +7,10 @@
 
 package sims.math
 
-/**An x3-axis aligned vector. Since SIMS is in 2D, 3D vectors are only used as a convenience to simulate operations that only exist
+/**A z-axis aligned vector. Since SiMS is in 2D, 3D vectors are only used as a convenience to simulate operations that only exist
  * in three dimensions such as the cross product.*/
-case class PseudoVector3D(x3: Double) {
+case class PseudoVector3D(z: Double) {
 	
-	def cross(v: Vector2D): Vector2D = v.leftNormal * x3
+	def cross(v: Vector2D): Vector2D = v.leftNormal * z
 	
 }
\ No newline at end of file
diff --git a/src/main/scala/sims/math/vector.scala b/src/main/scala/sims/math/vector.scala
index 8e7c716..83c2e2d 100644
--- a/src/main/scala/sims/math/vector.scala
+++ b/src/main/scala/sims/math/vector.scala
@@ -10,12 +10,14 @@ package sims.math
 import scala.math._
 
 /** A 2D vector.
+  * When used in a geometric context, all operations are related to a right-handed coordinate
+  * system and positive angles are given counter-clockwise.  
   * @param x 1st component
   * @param y 2nd component */
 case class Vector2D(x: Double, y: Double) {
-	
-	/** Components of this vector. */
-	lazy val components = List(x, y)
+  
+  /** Components of this vector. */
+  lazy val components = List(x, y)
     
   /** Vector addition. */
   def +(v: Vector2D): Vector2D = new Vector2D(x + v.x, y + v.y)
@@ -23,7 +25,7 @@ case class Vector2D(x: Double, y: Double) {
   /** Scalar multiplication. */
   def *(n: Double): Vector2D = new Vector2D(x * n, y * n)
   
-	/** Inverse of this vector. */
+  /** Inverse of this vector. */
   lazy val unary_- = this * (-1)
   
   /** Add inverse of another vector. */
@@ -35,19 +37,22 @@ case class Vector2D(x: Double, y: Double) {
   /** Dot product. */
   def dot(v: Vector2D): Double = x * v.x + y * v.y
   
-  /** Cross product. Length only because in 2D. The direction would be given by the x3-axis. */
+  /** Cross product. Length only because in 2D. The direction would be given by the z-axis. */
   def cross(v: Vector2D): Double = x * v.y - y * v.x
   
-  /** Cross product with an imaginary vector parallel to the x3-axis.
-    * Its magnitude is given by |p| and its direction sign(p). */
+  /** Cross product with an imaginary vector parallel to the z-axis.
+    * Its magnitude is given by `|p|` and its direction `sign(p)`. */
   def cross(p: PseudoVector3D): Vector2D = rightNormal * p.x3
   
   /** Magnitude of this vector. */
   lazy val length: Double = math.sqrt(lengthSquare)
 
+  /** Returns this vector's length to the square. This method should be preferred to simply
+    * `length` whenever possible since it is a lot faster. */
   lazy val lengthSquare: Double = x * x + y * y
   
-  /** Unit vector. */
+  /** Unit vector.
+    * @throws UnsupportedOperationException if invoked on null vector. */
   lazy val unit: UnitVector2D =
   	if (!(x == 0.0 && y == 0.0)) new UnitVector2D(x / length, y / length) 
     else throw new UnsupportedOperationException("Null vector does not have a unit vector.")
@@ -60,19 +65,19 @@ case class Vector2D(x: Double, y: Double) {
       Vector2D.Null
    }
 	
-	/** Returns the projection of this vector onto the unit vector `v`. */
-  def project(v: UnitVector2D): Vector2D = {
-    if (v != Vector2D.Null)
-      v * (this dot v)
+  /** Returns the projection of this vector onto the unit vector `u`. */
+  def project(u: UnitVector2D): Vector2D = {
+    if (u != Vector2D.Null)
+      u * (this dot u)
     else
       Vector2D.Null
    }
   
   /** Returns this vector rotated by `angle` radians. */
-  def rotate(angle: Double): Vector2D = {
-    Vector2D(cos(angle) * x - sin(angle) * y,
-             cos(angle) * y + sin(angle) * x)
-  }
+  def rotate(angle: Double): Vector2D = Vector2D(
+	cos(angle) * x - sin(angle) * y,
+    cos(angle) * y + sin(angle) * x
+  )
   
   /** Left normal vector. (-y, x) */
   lazy val leftNormal: Vector2D = Vector2D(-y, x)
@@ -86,37 +91,45 @@ case class Vector2D(x: Double, y: Double) {
   /** Colinearity check. */
   def ~(v: Vector2D): Boolean = x * v.y - v.x * y == 0
   
-  
+  /** Checks if this vector is pointing strictly to the left of the given vector. */
   def leftOf(v: Vector2D): Boolean = (this dot v.leftNormal) > 0
+  
+  /** Checks if this vector is pointing strictly to the right of the given vector. */
   def rightOf(v: Vector2D): Boolean = (this dot v.rightNormal) > 0
+  
+  /** Determines if this vector is pointing in the same direction of the given vector, rotated
+    * up to 90 degrees in any direction.
+    * This corresponds to checking if the dot product of this vector and the given one is
+    * strictly positive. */
   def directionOf(v: Vector2D): Boolean = (this dot v) > 0
   
 }
 	
 object Vector2D {
-	
-	/**Null vector.*/
+  
+  /** Null vector. */
   val Null = Vector2D(0,0)
   
-  /**Horizontal unit vector. (1,0)*/
+  /** Horizontal unit vector. (1,0) */
   val i = new UnitVector2D(1,0)
   
-  /**Vertical unit vector. (0,1)*/
+  /** Vertical unit vector. (0,1) */
   val j = new UnitVector2D(0,1)
 	
 }
 
-/** A two dimensional vector considered having a magnitude of one.
+/** A two dimensional vector always considered having a magnitude of one.
   * Unit vectors are used internally for increasing performance
-  * (i.e. the length of a unit vector is always one, the unit vector of
+  * (i.e. the length of a unit vector is always one; the unit vector of
   * a unit vector is always itself). */
 class UnitVector2D(x: Double, y: Double) extends Vector2D(x, y) {
 	
-	def isValid = x * x + y * y == 1
-	
-	override lazy val unit = this
+  /** Checks if this vector is really a unit vector, i.e. its length is 1. */
+  def isValid = x * x + y * y == 1
+  
+  override lazy val unit = this
 	
-	override lazy val length = 1.0
+  override lazy val length = 1.0
 
   override lazy val lengthSquare = 1.0