Improve the documentation for some angle methods

This commit is contained in:
Brendan Zabarauskas 2016-04-03 13:49:58 +10:00
parent aa6fd71ab8
commit 1d33c231e3

View file

@ -61,7 +61,12 @@ impl<S> From<Deg<S>> for Rad<S> 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 pub trait Angle where
Self: Copy + Clone, Self: Copy + Clone,
Self: PartialEq + PartialOrd, Self: PartialEq + PartialOrd,
@ -85,38 +90,175 @@ pub trait Angle where
if rem < Self::zero() { rem + Self::full_turn() } else { rem } 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] #[inline]
fn opposite(self) -> Self { fn opposite(self) -> Self {
Self::normalize(self + Self::turn_div_2()) Self::normalize(self + Self::turn_div_2())
} }
/// Returns the interior bisector of the two angles /// Returns the interior bisector of the two angles.
#[inline] #[inline]
fn bisect(self, other: Self) -> Self { fn bisect(self, other: Self) -> Self {
let half = cast(0.5f64).unwrap(); let half = cast(0.5f64).unwrap();
Self::normalize((self - other) * half + self) 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; fn zero() -> Self;
/// A full rotation.
fn full_turn() -> Self; fn full_turn() -> Self;
/// Half of a full rotation.
fn turn_div_2() -> Self; fn turn_div_2() -> Self;
/// A third of a full rotation.
fn turn_div_3() -> Self; fn turn_div_3() -> Self;
/// A quarter of a full rotation.
fn turn_div_4() -> Self; fn turn_div_4() -> Self;
/// A sixth of a full rotation.
fn turn_div_6() -> Self; 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; 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; 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; 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); fn sin_cos(self) -> (Self::Unitless, Self::Unitless);
#[inline] fn cot(self) -> Self::Unitless { Self::tan(self).recip() } /// Compute the cosecant of the angle.
#[inline] fn sec(self) -> Self::Unitless { Self::cos(self).recip() } ///
#[inline] fn csc(self) -> Self::Unitless { Self::sin(self).recip() } /// 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<f32> = 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<f32> = 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<f32> = 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; fn atan2(a: Self::Unitless, b: Self::Unitless) -> Self;
} }