[Branch,~jesse-barker/libmatrix/trunk] Rev 27: Finally add some documenting comments on the vector classes.

=== modified file 'vec.h'
--- vec.h	2011-09-20 20:43:03 +0000
+++ vec.h	2011-09-22 15:34:06 +0000
@@ -17,6 +17,10 @@ 
 
 namespace LibMatrix
 {
+// A template class for creating, managing and operating on a 2-element vector
+// of any type you like (intended for built-in types, but as long as it 
+// supports the basic arithmetic and assignment operators, any type should
+// work).
 template<typename T>
 class tvec2
 {
@@ -35,18 +39,26 @@ 
         y_(v.y_) {}
     ~tvec2() {}
 
+    // Print the elements of the vector to standard out.
+    // Really only useful for debug and test.
     void print() const
     {
         std::cout << "| " << x_ << " " << y_ << " |" << std::endl;
     }
+
+    // Allow raw data access for API calls and the like.
+    // For example, it is valid to pass a tvec2<float> into a call to
+    // the OpenGL command "glUniform2fv()".
     operator const T*() const { return &x_;}
 
+    // Get and set access members for the individual elements.
     const T x() const { return x_; }
     const T y() const { return y_; }
 
     void x(const T& val) { x_ = val; }
     void y(const T& val) { y_ = val; }
 
+    // A direct assignment of 'rhs' to this.
     tvec2& operator=(const tvec2& rhs)
     {
         if (this != &rhs)
@@ -57,6 +69,7 @@ 
         return *this;
     }
 
+    // Divide this by a scalar.  Return a reference to this.
     tvec2& operator/=(const T& rhs)
     {
         x_ /= rhs;
@@ -64,11 +77,14 @@ 
         return *this;
     }
 
+    // Divide a copy of this by a scalar.  Return the copy.
     const tvec2 operator/(const T& rhs) const
     {
         return tvec2(*this) /= rhs;
     }
 
+    // Component-wise divide of this by another vector.
+    // Return a reference to this.
     tvec2& operator/=(const tvec2& rhs)
     {
         x_ /= rhs.x_;
@@ -76,11 +92,14 @@ 
         return *this;
     }
 
+    // Component-wise divide of a copy of this by another vector.
+    // Return the copy.
     const tvec2 operator/(const tvec2& rhs) const
     {
         return tvec2(*this) /= rhs;
     }
 
+    // Multiply this by a scalar.  Return a reference to this.
     tvec2& operator*=(const T& rhs)
     {
         x_ *= rhs;
@@ -88,11 +107,14 @@ 
         return *this;
     }
 
+    // Multiply a copy of this by a scalar.  Return the copy.
     const tvec2 operator*(const T& rhs) const
     {
         return tvec2(*this) *= rhs;
     }
 
+    // Component-wise multiply of this by another vector.
+    // Return a reference to this.
     tvec2& operator*=(const tvec2& rhs)
     {
         x_ *= rhs.x_;
@@ -100,11 +122,14 @@ 
         return *this;
     }
 
+    // Component-wise multiply of a copy of this by another vector.
+    // Return the copy.
     const tvec2 operator*(const tvec2& rhs) const
     {
         return tvec2(*this) *= rhs;
     }
 
+    // Add a scalar to this.  Return a reference to this.
     tvec2& operator+=(const T& rhs)
     {
         x_ += rhs;
@@ -112,11 +137,14 @@ 
         return *this;
     }
     
+    // Add a scalar to a copy of this.  Return the copy.
     const tvec2 operator+(const T& rhs) const
     {
         return tvec2(*this) += rhs;
     }
 
+    // Component-wise addition of another vector to this.
+    // Return a reference to this.
     tvec2& operator+=(const tvec2& rhs)
     {
         x_ += rhs.x_;
@@ -124,11 +152,14 @@ 
         return *this;
     }
 
+    // Component-wise addition of another vector to a copy of this.
+    // Return the copy.
     const tvec2 operator+(const tvec2& rhs) const
     {
         return tvec2(*this) += rhs;
     }
 
+    // Subtract a scalar from this.  Return a reference to this.
     tvec2& operator-=(const T& rhs)
     {
         x_ -= rhs;
@@ -136,11 +167,14 @@ 
         return *this;
     }
     
+    // Subtract a scalar from a copy of this.  Return the copy.
     const tvec2 operator-(const T& rhs) const
     {
         return tvec2(*this) -= rhs;
     }
 
+    // Component-wise subtraction of another vector from this.
+    // Return a reference to this.
     tvec2& operator-=(const tvec2& rhs)
     {
         x_ -= rhs.x_;
@@ -148,16 +182,20 @@ 
         return *this;
     }
 
+    // Component-wise subtraction of another vector from a copy of this.
+    // Return the copy.
     const tvec2 operator-(const tvec2& rhs) const
     {
         return tvec2(*this) -= rhs;
     }
 
+    // Compute the length of this and return it.
     float length() const
     {
         return sqrt(dot(*this, *this));
     }
 
+    // Make this a unit vector.
     void normalize()
     {
         float l = length();
@@ -165,6 +203,7 @@ 
         y_ /= l;
     }
 
+    // Compute the dot product of two vectors.
     static T dot(const tvec2& v1, const tvec2& v2)
     {
         return (v1.x_ * v2.x_) + (v1.y_ * v2.y_); 
@@ -175,6 +214,10 @@ 
     T y_;
 };
 
+// A template class for creating, managing and operating on a 3-element vector
+// of any type you like (intended for built-in types, but as long as it 
+// supports the basic arithmetic and assignment operators, any type should
+// work).
 template<typename T>
 class tvec3
 {
@@ -197,12 +240,19 @@ 
         z_(v.z_) {}
     ~tvec3() {}
 
+    // Print the elements of the vector to standard out.
+    // Really only useful for debug and test.
     void print() const
     {
         std::cout << "| " << x_ << " " << y_ << " " << z_ << " |" << std::endl;
     }
+
+    // Allow raw data access for API calls and the like.
+    // For example, it is valid to pass a tvec3<float> into a call to
+    // the OpenGL command "glUniform3fv()".
     operator const T*() const { return &x_;}
 
+    // Get and set access members for the individual elements.
     const T x() const { return x_; }
     const T y() const { return y_; }
     const T z() const { return z_; }
@@ -211,6 +261,7 @@ 
     void y(const T& val) { y_ = val; }
     void z(const T& val) { z_ = val; }
 
+    // A direct assignment of 'rhs' to this.
     tvec3& operator=(const tvec3& rhs)
     {
         if (this != &rhs)
@@ -222,6 +273,7 @@ 
         return *this;
     }
 
+    // Divide this by a scalar.  Return a reference to this.
     tvec3& operator/=(const T& rhs)
     {
         x_ /= rhs;
@@ -230,11 +282,14 @@ 
         return *this;
     }
 
+    // Divide a copy of this by a scalar.  Return the copy.
     const tvec3 operator/(const T& rhs) const
     {
         return tvec3(*this) /= rhs;
     }
 
+    // Component-wise divide of this by another vector.
+    // Return a reference to this.
     tvec3& operator/=(const tvec3& rhs)
     {
         x_ /= rhs.x_;
@@ -243,11 +298,14 @@ 
         return *this;
     }
 
+    // Component-wise divide of a copy of this by another vector.
+    // Return the copy.
     const tvec3 operator/(const tvec3& rhs) const
     {
         return tvec3(*this) /= rhs;
     }
 
+    // Multiply this by a scalar.  Return a reference to this.
     tvec3& operator*=(const T& rhs)
     {
         x_ *= rhs;
@@ -256,11 +314,14 @@ 
         return *this;
     }
 
+    // Multiply a copy of this by a scalar.  Return the copy.
     const tvec3 operator*(const T& rhs) const
     {
         return tvec3(*this) *= rhs;
     }
 
+    // Component-wise multiply of this by another vector.
+    // Return a reference to this.
     tvec3& operator*=(const tvec3& rhs)
     {
         x_ *= rhs.x_;
@@ -269,11 +330,14 @@ 
         return *this;
     }
 
+    // Component-wise multiply of a copy of this by another vector.
+    // Return the copy.
     const tvec3 operator*(const tvec3& rhs) const
     {
         return tvec3(*this) *= rhs;
     }
 
+    // Add a scalar to this.  Return a reference to this.
     tvec3& operator+=(const T& rhs)
     {
         x_ += rhs;
@@ -282,11 +346,14 @@ 
         return *this;
     }
 
+    // Add a scalar to a copy of this.  Return the copy.
     const tvec3 operator+(const T& rhs) const
     {
         return tvec3(*this) += rhs;
     }
 
+    // Component-wise addition of another vector to this.
+    // Return a reference to this.
     tvec3& operator+=(const tvec3& rhs)
     {
         x_ += rhs.x_;
@@ -295,11 +362,14 @@ 
         return *this;
     }
 
+    // Component-wise addition of another vector to a copy of this.
+    // Return the copy.
     const tvec3 operator+(const tvec3& rhs) const
     {
         return tvec3(*this) += rhs;
     }
 
+    // Subtract a scalar from this.  Return a reference to this.
     tvec3& operator-=(const T& rhs)
     {
         x_ -= rhs;
@@ -308,11 +378,14 @@ 
         return *this;
     }
 
+    // Subtract a scalar from a copy of this.  Return the copy.
     const tvec3 operator-(const T& rhs) const
     {
         return tvec3(*this) -= rhs;
     }
 
+    // Component-wise subtraction of another vector from this.
+    // Return a reference to this.
     tvec3& operator-=(const tvec3& rhs)
     {
         x_ -= rhs.x_;
@@ -321,16 +394,20 @@ 
         return *this;
     }
 
+    // Component-wise subtraction of another vector from a copy of this.
+    // Return the copy.
     const tvec3 operator-(const tvec3& rhs) const
     {
         return tvec3(*this) -= rhs;
     }
 
+    // Compute the length of this and return it.
     float length() const
     {
         return sqrt(dot(*this, *this));
     }
 
+    // Make this a unit vector.
     void normalize()
     {
         float l = length();
@@ -339,11 +416,13 @@ 
         z_ /= l;
     }
 
+    // Compute the dot product of two vectors.
     static T dot(const tvec3& v1, const tvec3& v2)
     {
         return (v1.x_ * v2.x_) + (v1.y_ * v2.y_) + (v1.z_ * v2.z_); 
     }
 
+    // Compute the cross product of two vectors.
     static tvec3 cross(const tvec3& u, const tvec3& v)
     {
         return tvec3((u.y_ * v.z_) - (u.z_ * v.y_),
@@ -357,6 +436,10 @@ 
     T z_;
 };
 
+// A template class for creating, managing and operating on a 4-element vector
+// of any type you like (intended for built-in types, but as long as it 
+// supports the basic arithmetic and assignment operators, any type should
+// work).
 template<typename T>
 class tvec4
 {
@@ -383,12 +466,19 @@ 
         w_(v.w_) {}
     ~tvec4() {}
 
+    // Print the elements of the vector to standard out.
+    // Really only useful for debug and test.
     void print() const
     {
         std::cout << "| " << x_ << " " << y_ << " " << z_ << " " << w_ << " |" << std::endl;
     }
+
+    // Allow raw data access for API calls and the like.
+    // For example, it is valid to pass a tvec4<float> into a call to
+    // the OpenGL command "glUniform4fv()".
     operator const T*() const { return &x_;}
 
+    // Get and set access members for the individual elements.
     const T x() const { return x_; }
     const T y() const { return y_; }
     const T z() const { return z_; }
@@ -399,6 +489,7 @@ 
     void z(const T& val) { z_ = val; }
     void w(const T& val) { w_ = val; }
 
+    // A direct assignment of 'rhs' to this.
     tvec4& operator=(const tvec4& rhs)
     {
         if (this != &rhs)
@@ -411,6 +502,7 @@ 
         return *this;
     }
 
+    // Divide this by a scalar.  Return a reference to this.
     tvec4& operator/=(const T& rhs)
     {
         x_ /= rhs;
@@ -420,11 +512,14 @@ 
         return *this;
     }
 
+    // Divide a copy of this by a scalar.  Return the copy.
     const tvec4 operator/(const T& rhs) const
     {
         return tvec4(*this) /= rhs;
     }
 
+    // Component-wise divide of this by another vector.
+    // Return a reference to this.
     tvec4& operator/=(const tvec4& rhs)
     {
         x_ /= rhs.x_;
@@ -434,11 +529,14 @@ 
         return *this;
     }
 
+    // Component-wise divide of a copy of this by another vector.
+    // Return the copy.
     const tvec4 operator/(const tvec4& rhs) const
     {
         return tvec4(*this) /= rhs;
     }
 
+    // Multiply this by a scalar.  Return a reference to this.
     tvec4& operator*=(const T& rhs)
     {
         x_ *= rhs;
@@ -448,11 +546,14 @@ 
         return *this;
     }
 
+    // Multiply a copy of this by a scalar.  Return the copy.
     const tvec4 operator*(const T& rhs) const
     {
         return tvec4(*this) *= rhs;
     }
 
+    // Component-wise multiply of this by another vector.
+    // Return a reference to this.
     tvec4& operator*=(const tvec4& rhs)
     {
         x_ *= rhs.x_;
@@ -462,11 +563,14 @@ 
         return *this;
     }
 
+    // Component-wise multiply of a copy of this by another vector.
+    // Return the copy.
     const tvec4 operator*(const tvec4& rhs) const
     {
         return tvec4(*this) *= rhs;
     }
 
+    // Add a scalar to this.  Return a reference to this.
     tvec4& operator+=(const T& rhs)
     {
         x_ += rhs;
@@ -476,11 +580,14 @@ 
         return *this;
     }
 
+    // Add a scalar to a copy of this.  Return the copy.
     const tvec4 operator+(const T& rhs) const
     {
         return tvec4(*this) += rhs;
     }
 
+    // Component-wise addition of another vector to this.
+    // Return a reference to this.
     tvec4& operator+=(const tvec4& rhs)
     {
         x_ += rhs.x_;
@@ -490,11 +597,14 @@ 
         return *this;
     }
 
+    // Component-wise addition of another vector to a copy of this.
+    // Return the copy.
     const tvec4 operator+(const tvec4& rhs) const
     {
         return tvec4(*this) += rhs;
     }
 
+    // Subtract a scalar from this.  Return a reference to this.
     tvec4& operator-=(const T& rhs)
     {
         x_ -= rhs;
@@ -504,11 +614,14 @@ 
         return *this;
     }
 
+    // Subtract a scalar from a copy of this.  Return the copy.
     const tvec4 operator-(const T& rhs) const
     {
         return tvec4(*this) -= rhs;
     }
 
+    // Component-wise subtraction of another vector from this.
+    // Return a reference to this.
     tvec4& operator-=(const tvec4& rhs)
     {
         x_ -= rhs.x_;
@@ -518,16 +631,20 @@ 
         return *this;
     }
 
+    // Component-wise subtraction of another vector from a copy of this.
+    // Return the copy.
     const tvec4 operator-(const tvec4& rhs) const
     {
         return tvec4(*this) -= rhs;
     }
 
+    // Compute the length of this and return it.
     float length() const
     {
         return sqrt(dot(*this, *this));
     }
 
+    // Make this a unit vector.
     void normalize()
     {
         float l = length();
@@ -537,6 +654,7 @@ 
         w_ /= l;
     }
 
+    // Compute the dot product of two vectors.
     static T dot(const tvec4& v1, const tvec4& v2)
     {
         return (v1.x_ * v2.x_) + (v1.y_ * v2.y_) + (v1.z_ * v2.z_) + (v1.w_ * v2.w_);