Improve the documentation for some angle methods

src/angle.rs

@@ -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
     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<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;
 }