From bb4154199bc69199d9ac2652493515ff920a50bb Mon Sep 17 00:00:00 2001 From: Brendan Zabarauskas Date: Wed, 5 Dec 2012 18:09:53 +1000 Subject: [PATCH] More documentation updates --- src/color/color.rs | 71 ++++++++++++++++++++++++++++----- src/mat.rs | 95 ++++++++++++++++++++++++++++++++------------ src/num/kinds.rs | 17 +++++++- src/quat.rs | 79 +++++++++++++++++++++++++++++-------- src/vec.rs | 98 ++++++++++++++++++++++++++++++++++++++-------- 5 files changed, 291 insertions(+), 69 deletions(-) diff --git a/src/color/color.rs b/src/color/color.rs index 821648e..7fdc813 100644 --- a/src/color/color.rs +++ b/src/color/color.rs @@ -15,7 +15,9 @@ use num::kinds::{Float, Number}; */ pub trait Color: Dimensional, ToPtr, Eq { /** - * Returns the color with each component inverted + * # Return value + * + * The color with each component inverted */ pure fn inverse(&self) -> self; @@ -30,7 +32,7 @@ pub trait Color: Dimensional, ToPtr, Eq { pure fn to_rgb_u8(&self) -> RGB; /** - * Convert the color to a RGB + * Convert the color to a `RGB` * * # Returns * @@ -144,6 +146,7 @@ pub trait Color4: Color { pure fn to_hsva_f64(&self) -> HSVA; } +// TODO!!! // pub trait ColorRGB { // static pure fn from_hex(hex: u8) -> self; // } @@ -221,7 +224,20 @@ pub pure fn to_rgb(color: &HSV) -> RGB { - +/** + * A RGB color type (red, green, blue) + * + * # Type parameters + * + * * `T` - A color component which should be one of the following primitive + * types: `u8`, `u16`, `u32`, `u64`, `f32` or `f64`. + * + * # Fields + * + * * `r` - the red component + * * `g` - the green component + * * `b` - the blue component + */ pub struct RGB { r: T, g: T, b: T } pub impl RGB { @@ -364,8 +380,21 @@ pub impl RGB: Eq { - - +/** + * A RGBA color type (red, green, blue, alpha) + * + * # Type parameters + * + * * `T` - A color component which should be one of the following primitive + * types: `u8`, `u16`, `u32`, `u64`, `f32` or `f64`. + * + * # Fields + * + * * `r` - the red component + * * `g` - the green component + * * `b` - the blue component + * * `a` - the alpha component + */ pub struct RGBA { r: T, g: T, b: T, a: T } pub impl RGBA { @@ -517,9 +546,19 @@ pub impl RGBA: Eq { - - - +/** + * A HSV color type (hue, saturation, value) + * + * # Type parameters + * + * * `T` - A color component which should be either an `f32` or `f64`. + * + * # Fields + * + * * `h` - the hue component in degrees (from 0.0 to 360.0) + * * `s` - the saturation component + * * `v` - the value (brightness) component + */ pub struct HSV { h: Degrees, s: T, v: T } pub impl HSV { @@ -638,8 +677,20 @@ pub impl HSV: Eq { - - +/** + * A HSVA color type (hue, saturation, value, alpha) + * + * # Type parameters + * + * * `T` - A color component which should be either an `f32` or `f64`. + * + * # Fields + * + * * `h` - the hue component in degrees (from 0.0 to 360.0) + * * `s` - the saturation component + * * `v` - the value (brightness) component + * * `v` - the alpha component + */ pub struct HSVA { h: Degrees, s: T, v: T, a: T } pub impl HSVA { diff --git a/src/mat.rs b/src/mat.rs index 2664427..e9fd8de 100644 --- a/src/mat.rs +++ b/src/mat.rs @@ -26,62 +26,86 @@ use vec::{NumericVector, Vec2, Vec3, Vec4}; */ pub trait Matrix: Dimensional, ToPtr, Eq, Neg { /** - * Returns the column vector at `i` + * # Return value + * + * The column vector at `i` */ pure fn col(&self, i: uint) -> V; /** - * Returns the row vector at `i` + * # Return value + * + * The row vector at `i` */ pure fn row(&self, i: uint) -> V; /** - * Returns the identity matrix + * # Return value + * + * The identity matrix */ static pure fn identity() -> self; /** - * Returns a matrix with all elements set to zero + * # Return value + * + * A matrix with all elements set to zero */ static pure fn zero() -> self; /** - * Returns the scalar multiplication of this matrix and `value` + * # Return value + * + * The scalar multiplication of this matrix and `value` */ pure fn mul_t(&self, value: T) -> self; /** - * Returns the matrix vector product of the matrix and `vec` + * # Return value + * + * The matrix vector product of the matrix and `vec` */ pure fn mul_v(&self, vec: &V) -> V; /** - * Ruturns the matrix addition of the matrix and `other` + * # Return value + * + * The matrix addition of the matrix and `other` */ pure fn add_m(&self, other: &self) -> self; /** - * Ruturns the difference between the matrix and `other` + * # Return value + * + * The difference between the matrix and `other` */ pure fn sub_m(&self, other: &self) -> self; /** - * Returns the matrix product of the matrix and `other` + * # Return value + * + * The matrix product of the matrix and `other` */ pure fn mul_m(&self, other: &self) -> self; /** - * Returns the matrix dot product of the matrix and `other` + * # Return value + * + * The matrix dot product of the matrix and `other` */ pure fn dot(&self, other: &self) -> T; /** - * Returns the determinant of the matrix + * # Return value + * + * The determinant of the matrix */ pure fn determinant(&self) -> T; /** - * Returns the sum of the main diagonal of the matrix + * # Return value + * + * The sum of the main diagonal of the matrix */ pure fn trace(&self) -> T; @@ -90,42 +114,61 @@ pub trait Matrix: Dimensional, ToPtr, Eq, Neg { * * # Return value * - * - `Some(m)` if the inversion was successful, where `m` is the inverted matrix - * - `None` if the inversion was unsuccessful (because the matrix was not invertable) + * * `Some(m)` - if the inversion was successful, where `m` is the inverted matrix + * * `None` - if the inversion was unsuccessful (because the matrix was not invertable) */ pure fn inverse(&self) -> Option; /** - * Returns the transpose of the matrix + * # Return value + * + * The transposed matrix */ pure fn transpose(&self) -> self; /** - * Returns `true` if the matrix is approximately equal to the - * identity matrix + * Check to see if the matrix is an identity matrix + * + * # Return value + * + * `true` if the matrix is approximately equal to the identity matrix */ pure fn is_identity(&self) -> bool; /** - * Returns `true` all the elements outside the main diagonal are - * approximately equal to zero. + * Check to see if the matrix is diagonal + * + * # Return value + * + * `true` all the elements outside the main diagonal are approximately + * equal to zero. */ pure fn is_diagonal(&self) -> bool; /** - * Returns `true` if the matrix is not approximately equal to the - * identity matrix. + * Check to see if the matrix is rotated + * + * # Return value + * + * `true` if the matrix is not approximately equal to the identity matrix. */ pure fn is_rotated(&self) -> bool; /** - * Returns `true` if the matrix is approximately symmetrical (ie, if the - * matrix is equal to its transpose). + * Check to see if the matrix is symmetric + * + * # Return value + * + * `true` if the matrix is approximately equal to its transpose). */ pure fn is_symmetric(&self) -> bool; /** - * Returns `true` if the matrix is invertable + * Check to see if the matrix is invertable + * + * # Return value + * + * `true` if the matrix is invertable */ pure fn is_invertible(&self) -> bool; } @@ -135,7 +178,9 @@ pub trait Matrix: Dimensional, ToPtr, Eq, Neg { */ pub trait MutableMatrix: Matrix { /** - * Get a mutable reference to the column at `i` + * # Return value + * + * A mutable reference to the column at `i` */ fn col_mut(&mut self, i: uint) -> &self/mut V; diff --git a/src/num/kinds.rs b/src/num/kinds.rs index 8ca027a..d2c5619 100644 --- a/src/num/kinds.rs +++ b/src/num/kinds.rs @@ -7,7 +7,22 @@ use num::default_eq::DefaultEq; pub trait Number: DefaultEq, Eq, Num, NumConv, Ord { /** - * Construct a number from the type `T:Number` + * Cast a number to the type surrounding the static method + * + * # Type parameters + * + * `T` - The type of the number which will be cast. + * + * # Return value + * + * `n` cast to the type surrounding the static method + * + * # Example + * + * ~~~ + * let twenty: f32 = Number::from(0x14); + * assert twenty == 20f32; + * ~~~ */ static pure fn from(n: T) -> self; diff --git a/src/quat.rs b/src/quat.rs index d3243a7..bb1f1d0 100644 --- a/src/quat.rs +++ b/src/quat.rs @@ -1,3 +1,12 @@ +/** + * > Every morning in the early part of October 1843, on my coming down to + * breakfast, your brother William Edward and yourself used to ask me: "Well, + * Papa, can you multiply triples?" Whereto I was always obliged to reply, + * with a sad shake of the head, "No, I can only add and subtract them." + * + * Sir William Hamilton + */ + use core::cast::transmute; use core::cmp::{Eq, Ord}; use core::ptr::to_unsafe_ptr; @@ -21,90 +30,122 @@ use vec::Vec3; * # Type parameters * * * `T` - The type of the components. Should be a floating point type. - * * `V3` - The 3-dimensional vector containing the three imaginary components - * of the quaternion. + * * `V3` - The 3-dimensional vector type that will containin the imaginary + * components of the quaternion. */ pub trait Quaternion: Dimensional, ToPtr, Eq, Neg { /** - * Returns the multiplicative identity, ie: `q = 1 + 0i + 0j + 0i` + * # Return value + * + * The multiplicative identity, ie: `q = 1 + 0i + 0j + 0i` */ static pure fn identity() -> self; /** - * Returns the additive identity, ie: `q = 0 + 0i + 0j + 0i` + * # Return value + * + * The additive identity, ie: `q = 0 + 0i + 0j + 0i` */ static pure fn zero() -> self; /** - * Returns the result of multiplying the quaternion a scalar + * # Return value + * + * The result of multiplying the quaternion a scalar */ pure fn mul_t(&self, value: T) -> self; /** - * Returns the result of dividing the quaternion a scalar + * # Return value + * + * The result of dividing the quaternion a scalar */ pure fn div_t(&self, value: T) -> self; /** - * Returns the result of multiplying the quaternion by a vector + * # Return value + * + * The result of multiplying the quaternion by a vector */ pure fn mul_v(&self, vec: &V3) -> V3; /** - * Returns the sum of this quaternion and `other` + * # Return value + * + * The sum of this quaternion and `other` */ pure fn add_q(&self, other: &self) -> self; /** - * Returns the sum of this quaternion and `other` + * # Return value + * + * The sum of this quaternion and `other` */ pure fn sub_q(&self, other: &self) -> self; /** - * Returns the the result of multipliplying the quaternion by `other` + * # Return value + * + * The the result of multipliplying the quaternion by `other` */ pure fn mul_q(&self, other: &self) -> self; /** + * # Return value + * * The dot product of the quaternion and `other` */ pure fn dot(&self, other: &self) -> T; /** - * Returns the conjugate of the quaternion + * # Return value + * + * The conjugate of the quaternion */ pure fn conjugate(&self) -> self; /** - * Returns the multiplicative inverse of the quaternion + * # Return value + * + * The multiplicative inverse of the quaternion */ pure fn inverse(&self) -> self; /** - * Returns the squared magnitude of the quaternion. This is useful for + * # Return value + * + * The squared magnitude of the quaternion. This is useful for * magnitude comparisons where the exact magnitude does not need to be * calculated. */ pure fn magnitude2(&self) -> T; /** - * Returns the magnitude of the quaternion + * # Return value + * + * The magnitude of the quaternion * * # Performance notes * - * For instances where the exact magnitude of the vector does not need to be - * known, for example for quaternion-quaternion magnitude comparisons, + * 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. */ pure fn magnitude(&self) -> T; /** - * Returns the normalized quaternion + * # Return value + * + * The normalized quaternion */ pure fn normalize(&self) -> self; /** * Normalised linear interpolation + * + * # Return value + * + * The intoperlated quaternion */ pure fn nlerp(&self, other: &self, amount: T) -> self; @@ -112,6 +153,10 @@ pub trait Quaternion: Dimensional, ToPtr, Eq, Neg { * Perform a spherical linear interpolation between the quaternion and * `other`. * + * # Return value + * + * The intoperlated quaternion + * * # Performance notes * * This is more accurate than `nlerp` but is also more diff --git a/src/vec.rs b/src/vec.rs index 8d4976c..61d376d 100644 --- a/src/vec.rs +++ b/src/vec.rs @@ -66,7 +66,7 @@ pub trait NumericVector: Vector, Neg { /** * The standard basis vector * - * # Returns + * # Return value * * A vector with each component set to one */ @@ -75,34 +75,44 @@ pub trait NumericVector: Vector, Neg { /** * The null vector * - * # Returns + * # Return value * * A vector with each component set to zero */ static pure fn zero() -> self; /** - * Returns the scalar multiplication of the vector and `value` + * # Return value + * + * The scalar multiplication of the vector and `value` */ pure fn mul_t(&self, value: T) -> self; /** - * Returns the scalar division of the vector and `value` + * # Return value + * + * The scalar division of the vector and `value` */ pure fn div_t(&self, value: T) -> self; /** - * Returns the sum of the vector and `other` + * # Return value + * + * The sum of the vector and `other` */ pure fn add_v(&self, other: &self) -> self; /** - * Returns the difference between the vector and `other` + * # Return value + * + * The difference between the vector and `other` */ pure fn sub_v(&self, other: &self) -> self; /** - * Returns the dot product of the vector and `other` + * # Return value + * + * The dot product of the vector and `other` */ pure fn dot(&self, other: &self) -> T; } @@ -154,7 +164,9 @@ pub trait NumericVector3: NumericVector { // static pure fn unit_z() -> self; /** - * Returns the cross product of the vector and `other` + * # Return value + * + * The cross product of the vector and `other` */ pure fn cross(&self, other: &self) -> self; } @@ -188,32 +200,53 @@ pub trait NumericVector4: NumericVector { */ pub trait EuclideanVector: NumericVector { /** - * Returns the squared length of the vector + * # Return value + * + * The squared length of the vector. This is useful for comparisons where + * the exact length does not need to be calculated. */ pure fn length2(&self) -> T; /** - * Returns the length of the vector + * # Return value + * + * The length of the vector + * + * # Performance notes + * + * 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. */ pure fn length(&self) -> T; /** - * Returns the squared distance between the vector and `other`. + * # Return value + * + * The squared distance between the vector and `other`. */ pure fn distance2(&self, other: &self) -> T; /** - * Returns the distance between the vector and `other` + * # Return value + * + * The distance between the vector and `other` */ pure fn distance(&self, other: &self) -> T; /** - * Returns the normalized vector + * # Return value + * + * The normalized vector */ pure fn normalize(&self) -> self; /** * Linearly intoperlate between the vector and `other` + * + * # Return value + * + * The intoperlated vector */ pure fn lerp(&self, other: &self, amount: T) -> self; } @@ -243,7 +276,17 @@ pub trait MutableEuclideanVector: MutableNumericVector<&self/T>, /** - * Vec2 + * A 2-dimensional vector + * + * # Type parameters + * + * * `T` - The type of the components. This is intended to support boolean, + * integer, unsigned integer, and floating point types. + * + * # Fields + * + * * `x` - the first component of the vector + * * `y` - the second component of the vector */ pub struct Vec2 { x: T, y: T } @@ -468,7 +511,18 @@ pub impl Vec2: DefaultEq { /** - * Vec3 + * A 3-dimensional vector + * + * # Type parameters + * + * * `T` - The type of the components. This is intended to support boolean, + * integer, unsigned integer, and floating point types. + * + * # Fields + * + * * `x` - the first component of the vector + * * `y` - the second component of the vector + * * `z` - the third component of the vector */ pub struct Vec3 { x: T, y: T, z: T } @@ -724,7 +778,19 @@ pub impl Vec3: DefaultEq { /** - * Vec4 + * A 4-dimensional vector + * + * # Type parameters + * + * * `T` - The type of the components. This is intended to support boolean, + * integer, unsigned integer, and floating point types. + * + * # Fields + * + * * `x` - the first component of the vector + * * `y` - the second component of the vector + * * `z` - the third component of the vector + * * `w` - the fourth component of the vector */ pub struct Vec4 { x: T, y: T, z: T, w: T }