Update comment documentation

src/funs/common.rs

@@ -1,12 +1,15 @@
+/**
+ * Common Functions
+ *
+ * This module corresponds to Section 8.3 of the [GLSL 4.30.6 specification]
+ * (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf).
+ */
+
 use num::cast::cast;
 use vec::{Vec2, Vec3, Vec4};
 
-/// Should only be implemented on signed types.
 pub trait Sign {
     pure fn abs() -> self;
-    
-    /// returns `-1` if the number is negative, `0` if the number is equal to 0,
-    /// and `1` if the number is positive
     pure fn sign() -> self;
 }
 

src/funs/exponential.rs

@@ -1,6 +1,10 @@
 /**
  * Exponential Functions
+ *
+ * This module corresponds to Section 8.2 of the [GLSL 4.30.6 specification]
+ * (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf).
  */
+
 use num::cast::{NumCast, cast};
 use vec::{Vec2, Vec3, Vec4};
 

src/funs/projection.rs

@@ -5,12 +5,12 @@ use num::cast::cast;
 use num::consts::pi;
 use num::ext::FloatExt;
 
-//
+/**
-//  Create a perspective projection matrix
+ * Create a perspective projection matrix
-//
+ *
-//  fov is in degrees
+ * This is the equivalent of the gluPerspective function, the algorithm of which
-//  http://www.opengl.org/wiki/GluPerspective_code
+ * can be found [here](http://www.opengl.org/wiki/GluPerspective_code).
-//
+ */
 #[inline(always)]
 pure fn perspective<T:Copy FloatExt>(fovy: Radians<T>, aspectRatio: T, near: T, far: T) -> Mat4<T> {
     let ymax = near * tan(&fovy);
@@ -19,18 +19,16 @@ pure fn perspective<T:Copy FloatExt>(fovy: Radians<T>, aspectRatio: T, near: T,
     frustum(-xmax, xmax, -ymax, ymax, near, far)
 }
 
-//
+/**
-//  Define a view frustrum
+ * Define a view frustrum
-//  http://www.felixgers.de/teaching/jogl/perspectiveProjection.html
+ *
-//  http://www.opengl.org/wiki/GluPerspective_code
+ * This is the equivalent of the now deprecated [glFrustrum]
-//
+ * (http://www.opengl.org/sdk/docs/man2/xhtml/glFrustum.xml) function.
-//  TODO: double check algorithm
+ */
-//
 #[inline(always)]
 pure fn frustum<T:Copy FloatExt>(left: T, right: T, bottom: T, top: T, near: T, far: T) -> Mat4<T> {
     let _0: T = cast(0);
     let _2: T = cast(2);
-    let neg_1 = cast(-1);
     
     let c0r0 = (_2 * near) / (right - left);
     let c0r1 = _0;
@@ -43,7 +41,7 @@ pure fn frustum<T:Copy FloatExt>(left: T, right: T, bottom: T, top: T, near: T,
     let c2r0 = (right + left) / (right - left);
     let c2r1 = (top + bottom) / (top - bottom);
     let c2r2 = -(far + near) / (far - near);
-    let c2r3 = neg_1;
+    let c2r3 = cast(-1);
     let c3r0 = _0;
     let c3r1 = _0;
     let c3r2 = -(_2 * far * near) / (far - near);

src/funs/relational.rs

@@ -1,9 +1,11 @@
 /**
  * Vector Relational Functions
+ *
+ * This module corresponds to Section 8.7 of the [GLSL 4.30.6 specification]
+ * (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf).
  */
 
 use core::cmp::{Eq, Ord};
-
 use vec::{Vector, Vec2, Vec3, Vec4};
 
 pub trait RelVector<BVec> {

src/funs/triganomic.rs

@@ -1,3 +1,9 @@
+/**
+ * Angle and Trigonometry Functions
+ *
+ * This module corresponds to Section 8.1 of the [GLSL 4.30.6 specification]
+ * (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf).
+ */
 use num::cast::{NumCast, cast};
 use angle::Radians;
 use vec::{Vec3, Vec2, Vec4};

src/gltypes.rs

@@ -1,24 +1,24 @@
-///
+/***
-/// This module contains various type aliases and method wrappers to make working
+ * This module contains various type aliases and method wrappers to make working
-/// with OpenGL cleaner and safer than working with the lmath types directly.
+ * with OpenGL cleaner and safer than working with the lmath types directly.
-/// This is especially important when working with type-sensitive OpenGL functions
+ * This is especially important when working with type-sensitive OpenGL functions
-/// such as `glVertexAttribPointer` and `glUniformMatrix4fv`) where a simple mistake
+ * such as `glVertexAttribPointer` and `glUniformMatrix4fv`) where a simple mistake
-/// such writing `Vec3::new(1, 2, 3)` or `Vec3::new(1f, 2f, 3f)` as opposed to
+ * such writing `Vec3::new(1, 2, 3)` or `Vec3::new(1f, 2f, 3f)` as opposed to
-/// `Vec3::new(1f32, 2f32, 3f32)` could cause you an afternoon of pain.
+ * `Vec3::new(1f32, 2f32, 3f32)` could cause you an afternoon of pain.
-///
+ *
-/// To give you an example of how using the wrapper methods can clean up your
+ * To give you an example of how using the wrapper methods can clean up your
-/// code and make debugging far easier, instead of writing:
+ * code and make debugging far easier, instead of writing:
-///
+ *
-/// ~~~
+ * ~~~
-/// let v: Mat4<f64> = NumericMatrixNxN::identity();
+ * let v: Mat4<f64> = NumericMatrixNxN::identity();
-/// ~~~
+ * ~~~
-///
+ *
-/// you can write:
+ * you can write:
-///
+ *
-/// ~~~
+ * ~~~
-/// let v = dmat4::identity();
+ * let v = dmat4::identity();
-/// ~~~
+ * ~~~
-///
+ */
 
 use core::sys::size_of;
 
@@ -27,7 +27,8 @@ use vec::{Vector, NumericVector, Vec2, Vec3, Vec4};
 use quat::{/*Quaternion, */Quat};
 
 
-// Vector aliases
+// Vector aliases, corresponding to Section 4.1.5 of the [GLSL 4.30.6 specification]
+// (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf).
 
 pub type vec2  = Vec2<f32>;             /// a two-component single-precision floating-point vector
 pub type vec3  = Vec3<f32>;             /// a three-component single-precision floating-point vector
@@ -207,7 +208,8 @@ pub impl uvec4 {
 }
 
 
-// Matrix aliases
+// Matrix aliases, corresponding to Section 4.1.6 of the [GLSL 4.30.6 specification]
+// (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf).
 
 pub type mat2 = mat2x2;                 /// a 2×2 single-precision floating-point matrix
 pub type mat3 = mat3x3;                 /// a 3×3 single-precision floating-point matrix

src/num/ext.rs

@@ -1,11 +1,3 @@
-/**
- * Various traits intended to be used with the built in numeric types. These
- * allow one to be more specific with trait bounds when using generics.
- *
- * Note: These traits won't be able to be used to their full potential until
- * trait inheritence is implemented.
- */
-
 use core::cmp::{Eq, Ord};
 
 use std::cmp::FuzzyEq;

src/num/rhs.rs

@@ -1,32 +1,33 @@
-/// These RHS operator traits would formalise the overloading of the RHS of the 
+/**
-/// Num operators (as described in [Refining Traits and Impls]
+ * These RHS operator traits would formalise the overloading of the RHS of the 
-/// (http:///smallcultfollowing.com/babysteps/blog/2012/10/04/refining-traits-slash-impls/)
+ * Num operators (as described in [Refining Traits and Impls]
-/// by nmatsakis). For example, if you wanted to achieve something like:
+ * (http://smallcultfollowing.com/babysteps/blog/2012/10/04/refining-traits-slash-impls/)
-///
+ * by nmatsakis). For example, if you wanted to achieve something like:
-/// ~~~
+ *
-/// enum Radians<T> = T;
+ * ~~~
-///
+ * enum Radians<T> = T;
-/// let half_rotation = Radians(float::consts::pi);
+ *
-/// let full_rotation = 2.0 * half_rotation;
+ * let half_rotation = Radians(float::consts::pi);
-/// let quarter_rotation = half_rotation * 0.5;
+ * let full_rotation = 2.0 * half_rotation;
-/// ~~~
+ * let quarter_rotation = half_rotation * 0.5;
-///
+ * ~~~
-/// All you'd have to implement is:
+ *
-///
+ * All you'd have to implement is:
-/// ~~~
+ *
-/// pub impl Radians<float>: float::MulRHS<Radians<float>> {
+ * ~~~
-///     pure fn int_add_rhs(lhs: &int) -> Radians<float> { Radians(lhs * (*self)) }
+ * pub impl Radians<float>: float::MulRHS<Radians<float>> {
-/// }
+ *     pure fn int_add_rhs(lhs: &int) -> Radians<float> { Radians(lhs * (*self)) }
-///
+ * }
-/// pub impl<T:Copy Num> Radians<T>: Mul<T, Radians<T>> {
+ *
-///     pure fn mul(rhs: &T) -> Radians<T> { Radians((*self) * (*rhs)) }
+ * pub impl<T:Copy Num> Radians<T>: Mul<T, Radians<T>> {
-/// }
+ *     pure fn mul(rhs: &T) -> Radians<T> { Radians((*self) * (*rhs)) }
-/// ~~~
+ * }
-///
+ * ~~~
-/// I may have got something wrong in my implementations, as I got some 'multiple
+ *
-/// applicable methods in scope' errors due to Num automatically being imported
+ * I may have got something wrong in my implementations, as I got some 'multiple
-/// with core. If that's the case, apologies in advance!
+ * applicable methods in scope' errors due to Num automatically being imported
-///
+ * with core. If that's the case, apologies in advance!
+ */
 
 use core::Num;