Use /// style doc comments

src/quat.rs

@@ -22,56 +22,46 @@ use vec::{Vec3, BaseVec3, AffineVec, NumVec, NumVec3};
 
 use num::NumAssign;
 
-/**
+/// A quaternion in scalar/vector form
- * A quaternion in scalar/vector form
+///
- *
+/// # Type parameters
- * # Type parameters
+///
- *
+/// - `T`: The type of the components. Should be a floating point type.
- * * `T` - The type of the components. Should be a floating point type.
+///
- *
+/// # Fields
- * # Fields
+///
- *
+/// - `s`: the scalar component
- * * `s` - the scalar component
+/// - `v`: a vector containing the three imaginary components
- * * `v` - a vector containing the three imaginary components
- */
 #[deriving(Eq)]
 pub struct Quat<T> { s: T, v: Vec3<T> }
 
 pub impl<T:Copy + Float + NumAssign> Quat<T> {
-    /**
+    /// Construct the quaternion from one scalar component and three
-     * Construct the quaternion from one scalar component and three
+    /// imaginary components
-     * imaginary components
+    ///
-     *
+    /// # Arguments
-     * # Arguments
+    ///
-     *
+    /// - `w`: the scalar component
-     * * `w`  - the scalar component
+    /// - `xi`: the fist imaginary component
-     * * `xi` - the fist imaginary component
+    /// - `yj`: the second imaginary component
-     * * `yj` - the second imaginary component
+    /// - `zk`: the third imaginary component
-     * * `zk` - the third imaginary component
-     */
     #[inline(always)]
     fn new(w: T, xi: T, yj: T, zk: T) -> Quat<T> {
         Quat::from_sv(w, BaseVec3::new(xi, yj, zk))
     }
 
-    /**
+    /// Construct the quaternion from a scalar and a vector
-     * Construct the quaternion from a scalar and a vector
+    ///
-     *
+    /// # Arguments
-     * # Arguments
+    ///
-     *
+    /// - `s`: the scalar component
-     * * `s` - the scalar component
+    /// - `v`: a vector containing the three imaginary components
-     * * `v` - a vector containing the three imaginary components
-     */
     #[inline(always)]
     fn from_sv(s: T, v: Vec3<T>) -> Quat<T> {
         Quat { s: s, v: v }
     }
 
-    /**
+    /// The multiplicative identity, ie: `q = 1 + 0i + 0j + 0i`
-     * # Return value
-     *
-     * The multiplicative identity, ie: `q = 1 + 0i + 0j + 0i`
-     */
     #[inline(always)]
     fn identity() -> Quat<T> {
         Quat::new(One::one(),
@@ -80,11 +70,7 @@ pub impl<T:Copy + Float + NumAssign> Quat<T> {
                   Zero::zero())
     }
 
-    /**
+    /// The additive identity, ie: `q = 0 + 0i + 0j + 0i`
-     * # Return value
-     *
-     * The additive identity, ie: `q = 0 + 0i + 0j + 0i`
-     */
     #[inline(always)]
     fn zero() -> Quat<T> {
         Quat::new(Zero::zero(),
@@ -163,11 +149,7 @@ pub impl<T:Copy + Float + NumAssign> Quat<T> {
         let m: Mat3<T> = BaseMat3::look_at(dir, up); m.to_quat()
     }
 
-    /**
+    /// The result of multiplying the quaternion a scalar
-     * # Return value
-     *
-     * The result of multiplying the quaternion a scalar
-     */
     #[inline(always)]
     fn mul_t(&self, value: T) -> Quat<T> {
         Quat::new(*self.index(0) * value,
@@ -176,11 +158,7 @@ pub impl<T:Copy + Float + NumAssign> Quat<T> {
                   *self.index(3) * value)
     }
 
-    /**
+    /// The result of dividing the quaternion a scalar
-     * # Return value
-     *
-     * The result of dividing the quaternion a scalar
-     */
     #[inline(always)]
     fn div_t(&self, value: T) -> Quat<T> {
         Quat::new(*self.index(0) / value,
@@ -189,22 +167,14 @@ pub impl<T:Copy + Float + NumAssign> Quat<T> {
                   *self.index(3) / value)
     }
 
-    /**
+    /// The result of multiplying the quaternion by a vector
-     * # Return value
-     *
-     * The result of multiplying the quaternion by a vector
-     */
     #[inline(always)]
     fn mul_v(&self, vec: &Vec3<T>) -> Vec3<T>  {
         let tmp = self.v.cross(vec).add_v(&vec.mul_t(self.s));
         self.v.cross(&tmp).mul_t(num::cast(2)).add_v(vec)
     }
 
-    /**
+    /// The sum of this quaternion and `other`
-     * # Return value
-     *
-     * The sum of this quaternion and `other`
-     */
     #[inline(always)]
     fn add_q(&self, other: &Quat<T>) -> Quat<T> {
         Quat::new(*self.index(0) + *other.index(0),
@@ -213,11 +183,7 @@ pub impl<T:Copy + Float + NumAssign> Quat<T> {
                   *self.index(3) + *other.index(3))
     }
 
-    /**
+    /// The sum of this quaternion and `other`
-     * # Return value
-     *
-     * The sum of this quaternion and `other`
-     */
     #[inline(always)]
     fn sub_q(&self, other: &Quat<T>) -> Quat<T> {
         Quat::new(*self.index(0) - *other.index(0),
@@ -226,11 +192,7 @@ pub impl<T:Copy + Float + NumAssign> Quat<T> {
                   *self.index(3) - *other.index(3))
     }
 
-    /**
+    /// The the result of multipliplying the quaternion by `other`
-     * # Return value
-     *
-     * The the result of multipliplying the quaternion by `other`
-     */
     #[inline(always)]
     fn mul_q(&self, other: &Quat<T>) -> Quat<T> {
         Quat::new(self.s * other.s   - self.v.x * other.v.x - self.v.y * other.v.y - self.v.z * other.v.z,
@@ -239,107 +201,79 @@ pub impl<T:Copy + Float + NumAssign> Quat<T> {
                   self.s * other.v.z + self.v.z * other.s   + self.v.x * other.v.y - self.v.y * other.v.x)
     }
 
-    /**
+    /// The dot product of the quaternion and `other`
-     * # Return value
-     *
-     * The dot product of the quaternion and `other`
-     */
     #[inline(always)]
     fn dot(&self, other: &Quat<T>) -> T {
         self.s * other.s + self.v.dot(&other.v)
     }
 
-    /**
+    /// The conjugate of the quaternion
-     * # Return value
-     *
-     * The conjugate of the quaternion
-     */
     #[inline(always)]
     fn conjugate(&self) -> Quat<T> {
         Quat::from_sv(self.s, -self.v)
     }
 
-    /**
+    /// The multiplicative inverse of the quaternion
-     * # Return value
-     *
-     * The multiplicative inverse of the quaternion
-     */
     #[inline(always)]
     fn inverse(&self) -> Quat<T> {
         self.conjugate().div_t(self.magnitude2())
     }
 
-    /**
+    /// The squared magnitude of the quaternion. This is useful for
-     * # Return value
+    /// magnitude comparisons where the exact magnitude does not need to be
-     *
+    /// calculated.
-     * The squared magnitude of the quaternion. This is useful for
-     * magnitude comparisons where the exact magnitude does not need to be
-     * calculated.
-     */
     #[inline(always)]
     fn magnitude2(&self) -> T {
         self.s * self.s + self.v.length2()
     }
 
-    /**
+    /// The magnitude of the quaternion
-     * # Return value
+    ///
-     *
+    /// # Performance notes
-     * The magnitude of the quaternion
+    ///
-     *
+    /// For instances where the exact magnitude of the quaternion does not need
-     * # Performance notes
+    /// to be known, for example for quaternion-quaternion magnitude comparisons,
-     *
+    /// it is advisable to use the `magnitude2` method instead.
-     * For instances where the exact magnitude of the quaternion does not need
-     * to be known, for example for quaternion-quaternion magnitude comparisons,
-     * it is advisable to use the `magnitude2` method instead.
-     */
     #[inline(always)]
     fn magnitude(&self) -> T {
         self.magnitude2().sqrt()
     }
 
-    /**
+    /// The normalized quaternion
-     * # Return value
-     *
-     * The normalized quaternion
-     */
     #[inline(always)]
     fn normalize(&self) -> Quat<T> {
         self.mul_t(One::one::<T>()/self.magnitude())
     }
 
-    /**
+    /// Normalised linear interpolation
-     * Normalised linear interpolation
+    ///
-     *
+    /// # Return value
-     * # Return value
+    ///
-     *
+    /// The intoperlated quaternion
-     * The intoperlated quaternion
-     */
     #[inline(always)]
     fn nlerp(&self, other: &Quat<T>, amount: T) -> Quat<T> {
         self.mul_t(One::one::<T>() - amount).add_q(&other.mul_t(amount)).normalize()
     }
 
-    /**
+    /// Spherical Linear Intoperlation
-     * Spherical Linear Intoperlation
+    ///
-     *
+    /// Perform a spherical linear interpolation between the quaternion and
-     * Perform a spherical linear interpolation between the quaternion and
+    /// `other`. Both quaternions should be normalized first.
-     * `other`. Both quaternions should be normalized first.
+    ///
-     *
+    /// # Return value
-     * # Return value
+    ///
-     *
+    /// The intoperlated quaternion
-     * The intoperlated quaternion
+    ///
-     *
+    /// # Performance notes
-     * # Performance notes
+    ///
-     *
+    /// The `acos` operation used in `slerp` is an expensive operation, so unless
-     * The `acos` operation used in `slerp` is an expensive operation, so unless
+    /// your quarternions a far away from each other it's generally more advisable
-     * your quarternions a far away from each other it's generally more advisable
+    /// to use `nlerp` when you know your rotations are going to be small.
-     * to use `nlerp` when you know your rotations are going to be small.
+    ///
-     *
+    /// - [Understanding Slerp, Then Not Using It]
-     * - [Understanding Slerp, Then Not Using It]
+    ///   (http://number-none.com/product/Understanding%20Slerp,%20Then%20Not%20Using%20It/)
-     *   (http://number-none.com/product/Understanding%20Slerp,%20Then%20Not%20Using%20It/)
+    /// - [Arcsynthesis OpenGL tutorial]
-     * - [Arcsynthesis OpenGL tutorial]
+    ///   (http://www.arcsynthesis.org/gltut/Positioning/Tut08%20Interpolation.html)
-     *   (http://www.arcsynthesis.org/gltut/Positioning/Tut08%20Interpolation.html)
-     */
     #[inline(always)]
     fn slerp(&self, other: &Quat<T>, amount: T) -> Quat<T> {
         let dot = self.dot(other);
@@ -363,19 +297,13 @@ pub impl<T:Copy + Float + NumAssign> Quat<T> {
         }
     }
 
-    /**
+    /// A pointer to the first component of the quaternion
-     * # Return value
-     *
-     * A pointer to the first component of the quaternion
-     */
     #[inline(always)]
     fn to_ptr(&self) -> *T {
         unsafe { cast::transmute(self) }
     }
 
-    /**
+    /// Convert the quaternion to a 3 x 3 rotation matrix
-     * Convert the quaternion to a 3 x 3 rotation matrix
-     */
     #[inline(always)]
     fn to_mat3(&self) -> Mat3<T> {
         let x2 = self.v.x + self.v.x;

src/vec.rs

@@ -19,206 +19,129 @@ use std::num::{Zero, One};
 
 use num::NumAssign;
 
-/**
+/// The base generic vector trait.
- * The base generic vector trait.
+///
- *
+/// # Type parameters
- * # Type parameters
+///
- *
+/// - `T`: The type of the components. This is intended to support boolean,
- * * `T` - The type of the components. This is intended to support boolean,
+///        integer, unsigned integer, and floating point types.
- *         integer, unsigned integer, and floating point types.
- */
 pub trait BaseVec<T>: Eq {
+    /// The component of the vector at the index `i`
     fn index<'a>(&'a self, i: uint) -> &'a T;
 
-    /**
+    /// Construct the vector from a single value, copying it to each component
-     * Construct the vector from a single value, copying it to each component
-     */
     fn from_value(value: T) -> Self;
 
-    /**
+    /// A pointer to the first component of the vector
-     * # Return value
-     *
-     * A pointer to the first component of the vector
-     */
     fn to_ptr(&self) -> *T;
 
-    /**
+    /// Get a mutable reference to the component at `i`
-     * Get a mutable reference to the component at `i`
-     */
     fn index_mut<'a>(&'a mut self, i: uint) -> &'a mut T;
 
-    /**
+    /// Swap two components of the vector in place
-     * Swap two components of the vector in place
-     */
     fn swap(&mut self, a: uint, b: uint);
 }
 
-/**
+/// A generic 2-dimensional vector
- * A generic 2-dimensional vector
- */
 pub trait BaseVec2<T>: BaseVec<T> {
     fn new(x: T, y: T) -> Self;
 }
 
-/**
+/// A generic 3-dimensional vector
- * A generic 3-dimensional vector
- */
 pub trait BaseVec3<T>: BaseVec<T> {
     fn new(x: T, y: T, z: T) -> Self;
 }
 
-/**
+/// A generic 4-dimensional vector
- * A generic 4-dimensional vector
- */
 pub trait BaseVec4<T>: BaseVec<T> {
     fn new(x: T, y: T, z: T, w: T) -> Self;
 }
 
-/**
+/// A vector with numeric components
- * A vector with numeric components
- */
 pub trait NumVec<T>: BaseVec<T> + Neg<Self> {
-    /**
+    /// The standard basis vector
-     * The standard basis vector
+    ///
-     *
+    /// # Return value
-     * # Return value
+    ///
-     *
+    /// A vector with each component set to one
-     * A vector with each component set to one
-     */
     fn identity() -> Self;
 
-    /**
+    /// The null vector
-     * The null vector
+    ///
-     *
+    /// # Return value
-     * # Return value
+    ///
-     *
+    /// A vector with each component set to zero
-     * A vector with each component set to zero
-     */
     fn zero() -> Self;
 
-    /**
+    /// True if the vector is equal to zero
-     * # Return value
-     *
-     * True if the vector is equal to zero
-     */
     fn is_zero(&self) -> bool;
 
-    /**
+    /// The scalar multiplication of the vector and `value`
-     * # Return value
-     *
-     * The scalar multiplication of the vector and `value`
-     */
     fn mul_t(&self, value: T) -> Self;
 
-    /**
+    /// The scalar division of the vector and `value`
-     * # Return value
-     *
-     * The scalar division of the vector and `value`
-     */
     fn div_t(&self, value: T) -> Self;
 
-    /**
+    /// Component-wise vector addition
-     * Component-wise vector addition
-     */
     fn add_v(&self, other: &Self) -> Self;
 
-    /**
+    /// Component-wise vector subtraction
-     * Component-wise vector subtraction
-     */
     fn sub_v(&self, other: &Self) -> Self;
 
-    /**
+    /// Component-wise vector multiplication
-     * Component-wise vector multiplication
-     */
     fn mul_v(&self, other: &Self) -> Self;
 
-    /**
+    /// Component-wise vector division
-     * Component-wise vector division
-     */
     fn div_v(&self, other: &Self) -> Self;
 
-    /**
+    /// The dot product of the vector and `other`
-     * # Return value
-     *
-     * The dot product of the vector and `other`
-     */
     fn dot(&self, other: &Self) -> T;
 
-    /**
+    /// Negate the vector
-     * Negate the vector
-     */
     fn neg_self(&mut self);
 
-    /**
+    /// Multiply the vector by a scalar
-     * Multiply the vector by a scalar
-     */
     fn mul_self_t(&mut self, value: T);
 
-    /**
+    /// Divide the vector by a scalar
-     * Divide the vector by a scalar
-     */
     fn div_self_t(&mut self, value: T);
 
-    /**
+    /// Set the vector to the component-wise vector sum
-     * Set the vector to the component-wise vector sum
-     */
     fn add_self_v(&mut self, other: &Self);
 
-    /**
+    /// Set the vector to the component-wise vector difference
-     * Set the vector to the component-wise vector difference
-     */
     fn sub_self_v(&mut self, other: &Self);
 
-    /**
+    /// Set the vector to the component-wise vector product
-     * Set the vector to the component-wise vector product
-     */
     fn mul_self_v(&mut self, other: &Self);
 
-    /**
+    /// Set the vector to the component-wise vector quotient
-     * Set the vector to the component-wise vector quotient
-     */
     fn div_self_v(&mut self, other: &Self);
 }
 
-/**
+/// A 2-dimensional vector with numeric components
- * A 2-dimensional vector with numeric components
- */
 pub trait NumVec2<T>: NumVec<T> {
     fn unit_x() -> Self;
     fn unit_y() -> Self;
 
-    /**
+    /// The perp dot product of the vector and `other`
-     * # Return value
-     *
-     * The perp dot product of the vector and `other`
-     */
     fn perp_dot(&self, other: &Self) -> T;
 }
 
-/**
+/// A 3-dimensional vector with numeric components
- * A 3-dimensional vector with numeric components
- */
 pub trait NumVec3<T>: NumVec<T> {
     fn unit_x() -> Self;
     fn unit_y() -> Self;
     fn unit_z() -> Self;
 
-    /**
+    /// The cross product of the vector and `other`
-     * # Return value
-     *
-     * The cross product of the vector and `other`
-     */
     fn cross(&self, other: &Self) -> Self;
 
-    /**
+    /// Set to the cross product of the vector and `other`
-     * Set to the cross product of the vector and `other`
-     */
     fn cross_self(&mut self, other: &Self);
 }
 
-/**
+/// A 4-dimensional vector with numeric components
- * A 4-dimensional vector with numeric components
- */
 pub trait NumVec4<T>: NumVec<T> {
     fn unit_x() -> Self;
     fn unit_y() -> Self;
@@ -227,174 +150,106 @@ pub trait NumVec4<T>: NumVec<T> {
 }
 
 pub trait ToHomogeneous<H> {
-    /**
+    /// Convert to a homogenous coordinate
-     * Convert to a homogenous coordinate
-     */
     fn to_homogeneous(&self) -> H;
 }
 
-/**
+/// A Euclidean (or Affine) vector
- * A Euclidean (or Affine) vector
+///
- *
+/// # Type parameters
- * # Type parameters
+///
- *
+/// - `T`: The type of the components. This should be a floating point type.
- * * `T` - The type of the components. This should be a floating point type.
- */
 pub trait AffineVec<T>: NumVec<T> {
-    /**
+    /// The squared length of the vector. This is useful for comparisons where
-     * # Return value
+    /// the exact length does not need to be calculated.
-     *
-     * The squared length of the vector. This is useful for comparisons where
-     * the exact length does not need to be calculated.
-     */
     fn length2(&self) -> T;
 
-    /**
+    /// The length of the vector
-     * # Return value
+    ///
-     *
+    /// # Performance notes
-     * The length of the vector
+    ///
-     *
+    /// For instances where the exact length of the vector does not need to be
-     * # Performance notes
+    /// known, for example for quaternion-quaternion length comparisons,
-     *
+    /// it is advisable to use the `length2` method instead.
-     * For instances where the exact length of the vector does not need to be
-     * known, for example for quaternion-quaternion length comparisons,
-     * it is advisable to use the `length2` method instead.
-     */
     fn length(&self) -> T;
 
-    /**
+    /// The squared distance between the vector and `other`.
-     * # Return value
-     *
-     * The squared distance between the vector and `other`.
-     */
     fn distance2(&self, other: &Self) -> T;
 
-    /**
+    /// The distance between the vector and `other`
-     * # Return value
-     *
-     * The distance between the vector and `other`
-     */
     fn distance(&self, other: &Self) -> T;
 
-    /**
+    /// The angle between the vector and `other` in radians
-     * # Return value
-     *
-     * The angle between the vector and `other` in radians
-     */
     fn angle(&self, other: &Self) -> T;
 
-    /**
+    /// The normalized vector
-     * # Return value
-     *
-     * The normalized vector
-     */
     fn normalize(&self) -> Self;
 
-    /**
+    /// Set the length of the vector whilst preserving the direction
-     * Set the length of the vector whilst preserving the direction
-     */
     fn normalize_to(&self, length: T) -> Self;
 
-    /**
+    /// Linearly intoperlate between the vector and `other`
-     * Linearly intoperlate between the vector and `other`
+    ///
-     *
+    /// # Return value
-     * # Return value
+    ///
-     *
+    /// The intoperlated vector
-     * The intoperlated vector
-     */
     fn lerp(&self, other: &Self, amount: T) -> Self;
 
-    /**
+    /// Normalize the vector
-     * Normalize the vector
-     */
     fn normalize_self(&mut self);
 
-    /**
+    /// Set the vector to a specified length whilst preserving the direction
-     * Set the vector to a specified length whilst preserving the direction
-     */
     fn normalize_self_to(&mut self, length: T);
 
-    /**
+    /// Linearly intoperlate the vector towards `other`
-     * Linearly intoperlate the vector towards `other`
-     */
     fn lerp_self(&mut self, other: &Self, amount: T);
 }
 
-/**
+/// Component-wise vector comparison methods
- * Component-wise vector comparison methods
+///
- *
+/// The methods contained in this trait correspond to the relational functions
- * The methods contained in this trait correspond to the relational functions
+/// mentioned in Section 8.7 of the [GLSL 4.30.6 specification]
- * mentioned in Section 8.7 of the [GLSL 4.30.6 specification]
+/// (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf).
- * (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf).
- */
 pub trait OrdVec<T, BoolVec>: BaseVec<T> {
-    /**
+    /// Component-wise compare of `self < other`
-     * Component-wise compare of `self < other`
-     */
     fn less_than(&self, other: &Self) -> BoolVec;
 
-    /**
+    /// Component-wise compare of `self <= other`
-     * Component-wise compare of `self <= other`
-     */
     fn less_than_equal(&self, other: &Self) -> BoolVec;
 
-    /**
+    /// Component-wise compare of `self > other`
-     * Component-wise compare of `self > other`
-     */
     fn greater_than(&self, other: &Self) -> BoolVec;
 
-    /**
+    /// Component-wise compare of `self >= other`
-     * Component-wise compare of `self >= other`
-     */
     fn greater_than_equal(&self, other: &Self) -> BoolVec;
 }
 
-/**
+/// Component-wise equality comparison methods
- * Component-wise equality comparison methods
+///
- *
+/// The methods contained in this trait correspond to the relational functions
- * The methods contained in this trait correspond to the relational functions
+/// mentioned in Section 8.7 of the [GLSL 4.30.6 specification]
- * mentioned in Section 8.7 of the [GLSL 4.30.6 specification]
+/// (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf).
- * (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf).
- */
 pub trait EqVec<T, BoolVec>: BaseVec<T> {
-    /**
+    /// Component-wise compare of `self == other`
-     * Component-wise compare of `self == other`
-     */
     fn equal(&self, other: &Self) -> BoolVec;
 
-    /**
+    /// Component-wise compare of `self != other`
-     * Component-wise compare of `self != other`
-     */
     fn not_equal(&self, other: &Self) -> BoolVec;
 }
 
-/**
+/// A vector with boolean components
- * A vector with boolean components
+///
- *
+/// The methods contained in this trait correspond to the relational functions
- * The methods contained in this trait correspond to the relational functions
+/// mentioned in Section 8.7 of the [GLSL 4.30.6 specification]
- * mentioned in Section 8.7 of the [GLSL 4.30.6 specification]
+/// (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf).
- * (http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf).
- */
 pub trait BoolVec: BaseVec<bool> {
-    /**
+    /// `true` if of any component is `true`
-     * # Return value
-     *
-     * `true` if of any component is `true`
-     */
     fn any(&self) -> bool;
 
-    /**
+    /// `true` only if all components are `true`
-     * # Return value
-     *
-     * `true` only if all components are `true`
-     */
     fn all(&self) -> bool;
 
-    /**
+    /// the component-wise logical complement
-     * # Return value
-     *
-     * the component-wise logical complement
-     */
     fn not(&self) -> Self;
 }
 
@@ -523,19 +378,17 @@ macro_rules! zip_assign(
     ($a:ident[] $method:ident $b:ident ..4) => ({ zip_assign!($a[] $method $b ..3); $a.index_mut(3).$method(&$b); });
 )
 
-/**
+/// A 2-dimensional vector
- * A 2-dimensional vector
+///
- *
+/// # Type parameters
- * # Type parameters
+///
- *
+/// - `T`: The type of the components. This is intended to support boolean,
- * * `T` - The type of the components. This is intended to support boolean,
+///        integer, unsigned integer, and floating point types.
- *         integer, unsigned integer, and floating point types.
+///
- *
+/// # Fields
- * # Fields
+///
- *
+/// - `x`: the first component of the vector
- * * `x` - the first component of the vector
+/// - `y`: the second component of the vector
- * * `y` - the second component of the vector
- */
  #[deriving(Eq)]
 pub struct Vec2<T> { x: T, y: T }
 
@@ -904,20 +757,18 @@ vec2_type!(Vec2u32<u32>)
 vec2_type!(Vec2u64<u64>)
 vec2_type!(Vec2b<bool>)
 
-/**
+/// A 3-dimensional vector
- * A 3-dimensional vector
+///
- *
+/// # Type parameters
- * # Type parameters
+///
- *
+/// - `T`: The type of the components. This is intended to support boolean,
- * * `T` - The type of the components. This is intended to support boolean,
+///         integer, unsigned integer, and floating point types.
- *         integer, unsigned integer, and floating point types.
+///
- *
+/// # Fields
- * # Fields
+///
- *
+/// - `x`: the first component of the vector
- * * `x` - the first component of the vector
+/// - `y`: the second component of the vector
- * * `y` - the second component of the vector
+/// - `z`: the third component of the vector
- * * `z` - the third component of the vector
- */
 #[deriving(Eq)]
 pub struct Vec3<T> { x: T, y: T, z: T }
 
@@ -1309,21 +1160,19 @@ vec3_type!(Vec3u32<u32>)
 vec3_type!(Vec3u64<u64>)
 vec3_type!(Vec3b<bool>)
 
-/**
+/// A 4-dimensional vector
- * A 4-dimensional vector
+///
- *
+/// # Type parameters
- * # Type parameters
+///
- *
+/// - `T`: The type of the components. This is intended to support boolean,
- * * `T` - The type of the components. This is intended to support boolean,
+///         integer, unsigned integer, and floating point types.
- *         integer, unsigned integer, and floating point types.
+///
- *
+/// # Fields
- * # Fields
+///
- *
+/// - `x`: the first component of the vector
- * * `x` - the first component of the vector
+/// - `y`: the second component of the vector
- * * `y` - the second component of the vector
+/// - `z`: the third component of the vector
- * * `z` - the third component of the vector
+/// - `w`: the fourth component of the vector
- * * `w` - the fourth component of the vector
- */
 #[deriving(Eq)]
 pub struct Vec4<T> { x: T, y: T, z: T, w: T }