From 1d33c231e381cae340814ef3e5ed1d35f4872a22 Mon Sep 17 00:00:00 2001 From: Brendan Zabarauskas Date: Sun, 3 Apr 2016 13:49:58 +1000 Subject: [PATCH] Improve the documentation for some angle methods --- src/angle.rs | 160 ++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 151 insertions(+), 9 deletions(-) diff --git a/src/angle.rs b/src/angle.rs index 053f349..3429f42 100644 --- a/src/angle.rs +++ b/src/angle.rs @@ -61,7 +61,12 @@ impl From> for Rad where S: BaseFloat { } } -/// Operations on angles. +/// Angles and their associated trigonometric functions. +/// +/// Typed angles allow for the writing of self-documenting code that makes it +/// clear when semantic violations have occured - for example, adding degrees to +/// radians, or adding a number to an angle. +/// pub trait Angle where Self: Copy + Clone, Self: PartialEq + PartialOrd, @@ -85,38 +90,175 @@ pub trait Angle where if rem < Self::zero() { rem + Self::full_turn() } else { rem } } - /// Return the angle rotated by half a turn + /// Return the angle rotated by half a turn. #[inline] fn opposite(self) -> Self { Self::normalize(self + Self::turn_div_2()) } - /// Returns the interior bisector of the two angles + /// Returns the interior bisector of the two angles. #[inline] fn bisect(self, other: Self) -> Self { let half = cast(0.5f64).unwrap(); Self::normalize((self - other) * half + self) } + /// The additive identity. + /// + /// Adding this to another angle has no affect. + /// + /// For example: + /// + /// ```rust + /// use cgmath::prelude::*; + /// use cgmath::Deg; + /// + /// let v = Deg::new(180.0); + /// assert_eq!(v + Deg::zero(), v); + /// ``` fn zero() -> Self; + + /// A full rotation. fn full_turn() -> Self; + + /// Half of a full rotation. fn turn_div_2() -> Self; + + /// A third of a full rotation. fn turn_div_3() -> Self; + + /// A quarter of a full rotation. fn turn_div_4() -> Self; + + /// A sixth of a full rotation. fn turn_div_6() -> Self; + /// Compute the sine of the angle, returning a unitless ratio. + /// + /// ```rust + /// use cgmath::prelude::*; + /// use cgmath::Rad; + /// + /// let angle = Rad::new(35.0); + /// let ratio: f32 = Rad::sin(angle); + /// ``` fn sin(self) -> Self::Unitless; + + /// Compute the cosine of the angle, returning a unitless ratio. + /// + /// ```rust + /// use cgmath::prelude::*; + /// use cgmath::Rad; + /// + /// let angle = Rad::new(35.0); + /// let ratio: f32 = Rad::cos(angle); + /// ``` fn cos(self) -> Self::Unitless; + + /// Compute the tangent of the angle, returning a unitless ratio. + /// + /// ```rust + /// use cgmath::prelude::*; + /// use cgmath::Rad; + /// + /// let angle = Rad::new(35.0); + /// let ratio: f32 = Rad::tan(angle); + /// ``` fn tan(self) -> Self::Unitless; + + /// Compute the sine and cosine of the angle, returning the result as a + /// pair. + /// + /// This does not have any performance benefits, but calculating both the + /// sine and cosine of a single angle is a common operation. + /// + /// ```rust + /// use cgmath::prelude::*; + /// use cgmath::Rad; + /// + /// let angle = Rad::new(35.0); + /// let (s, c) = Rad::sin_cos(angle); + /// ``` fn sin_cos(self) -> (Self::Unitless, Self::Unitless); - #[inline] fn cot(self) -> Self::Unitless { Self::tan(self).recip() } - #[inline] fn sec(self) -> Self::Unitless { Self::cos(self).recip() } - #[inline] fn csc(self) -> Self::Unitless { Self::sin(self).recip() } + /// Compute the cosecant of the angle. + /// + /// This is the same a computing the reciprocal of `Self::sin`. + /// + /// ```rust + /// use cgmath::prelude::*; + /// use cgmath::Rad; + /// + /// let angle = Rad::new(35.0); + /// let ratio: f32 = Rad::csc(angle); + /// ``` + #[inline] + fn csc(self) -> Self::Unitless { + Self::sin(self).recip() + } + + /// Compute the secant of the angle. + /// + /// This is the same a computing the reciprocal of `Self::tan`. + /// + /// ```rust + /// use cgmath::prelude::*; + /// use cgmath::Rad; + /// + /// let angle = Rad::new(35.0); + /// let ratio: f32 = Rad::cot(angle); + /// ``` + #[inline] + fn cot(self) -> Self::Unitless { + Self::tan(self).recip() + } + + /// Compute the cotatangent of the angle. + /// + /// This is the same a computing the reciprocal of `Self::cos`. + /// + /// ```rust + /// use cgmath::prelude::*; + /// use cgmath::Rad; + /// + /// let angle = Rad::new(35.0); + /// let ratio: f32 = Rad::sec(angle); + /// ``` + #[inline] + fn sec(self) -> Self::Unitless { + Self::cos(self).recip() + } + + /// Compute the arcsine of the ratio, returning the resulting angle. + /// + /// ```rust + /// use cgmath::prelude::*; + /// use cgmath::Rad; + /// + /// let angle: Rad = Rad::asin(0.5); + /// ``` + fn asin(ratio: Self::Unitless) -> Self; + + /// Compute the arccosine of the ratio, returning the resulting angle. + /// + /// ```rust + /// use cgmath::prelude::*; + /// use cgmath::Rad; + /// + /// let angle: Rad = Rad::acos(0.5); + /// ``` + fn acos(ratio: Self::Unitless) -> Self; + + /// Compute the arctangent of the ratio, returning the resulting angle. + /// + /// ```rust + /// use cgmath::prelude::*; + /// use cgmath::Rad; + /// + /// let angle: Rad = Rad::atan(0.5); + /// ``` + fn atan(ratio: Self::Unitless) -> Self; - fn asin(a: Self::Unitless) -> Self; - fn acos(a: Self::Unitless) -> Self; - fn atan(a: Self::Unitless) -> Self; fn atan2(a: Self::Unitless, b: Self::Unitless) -> Self; }