Add some documentation for Rotation.

src/geometry/isometry.rs

@@ -26,19 +26,15 @@ use geometry::{Point, Translation};
 #[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
 #[cfg_attr(
     feature = "serde-serialize",
-    serde(bound(
+    serde(bound(serialize = "R: Serialize,
-        serialize = "R: Serialize,
                      DefaultAllocator: Allocator<N, D>,
-                     Owned<N, D>: Serialize"
+                     Owned<N, D>: Serialize"))
-    ))
 )]
 #[cfg_attr(
     feature = "serde-serialize",
-    serde(bound(
+    serde(bound(deserialize = "R: Deserialize<'de>,
-        deserialize = "R: Deserialize<'de>,
                        DefaultAllocator: Allocator<N, D>,
-                       Owned<N, D>: Deserialize<'de>"
+                       Owned<N, D>: Deserialize<'de>"))
-    ))
 )]
 pub struct Isometry<N: Real, D: DimName, R>
 where DefaultAllocator: Allocator<N, D>
@@ -96,7 +92,8 @@ impl<N: Real, D: DimName + Copy, R: Rotation<Point<N, D>> + Copy> Copy for Isome
 where
     DefaultAllocator: Allocator<N, D>,
     Owned<N, D>: Copy,
-{}
+{
+}
 
 impl<N: Real, D: DimName, R: Rotation<Point<N, D>> + Clone> Clone for Isometry<N, D, R>
 where DefaultAllocator: Allocator<N, D>
@@ -283,7 +280,6 @@ where DefaultAllocator: Allocator<N, D>
     ///                             0.5,       0.8660254, 20.0,
     ///                             0.0,       0.0,       1.0);
     ///
-    /// // The translation part should not have changed.
     /// assert_relative_eq!(iso.to_homogeneous(), expected, epsilon = 1.0e-6);
     /// ```
     #[inline]
@@ -305,7 +301,8 @@ impl<N: Real, D: DimName, R> Eq for Isometry<N, D, R>
 where
     R: Rotation<Point<N, D>> + Eq,
     DefaultAllocator: Allocator<N, D>,
-{}
+{
+}
 
 impl<N: Real, D: DimName, R> PartialEq for Isometry<N, D, R>
 where

src/geometry/quaternion.rs

@@ -941,7 +941,6 @@ impl<N: Real> UnitQuaternion<N> {
     ///                             0.5,       0.8660254, 0.0,
     ///                             0.0,       0.0,       1.0);
     ///
-    /// // The translation part should not have changed.
     /// assert_relative_eq!(*rot.matrix(), expected, epsilon = 1.0e-6);
     /// ```
     #[inline]
@@ -1019,7 +1018,6 @@ impl<N: Real> UnitQuaternion<N> {
     ///                             0.0,       0.0,       1.0, 0.0,
     ///                             0.0,       0.0,       0.0, 1.0);
     ///
-    /// // The translation part should not have changed.
     /// assert_relative_eq!(rot.to_homogeneous(), expected, epsilon = 1.0e-6);
     /// ```
     #[inline]

src/geometry/rotation.rs

@@ -43,7 +43,8 @@ impl<N: Scalar, D: DimName> Copy for Rotation<N, D>
 where
     DefaultAllocator: Allocator<N, D, D>,
     <DefaultAllocator as Allocator<N, D, D>>::Buffer: Copy,
-{}
+{
+}
 
 impl<N: Scalar, D: DimName> Clone for Rotation<N, D>
 where
@@ -107,28 +108,92 @@ impl<N: Scalar, D: DimName> Rotation<N, D>
 where DefaultAllocator: Allocator<N, D, D>
 {
     /// A reference to the underlying matrix representation of this rotation.
+    ///
+    /// # Example
+    /// ```
+    /// # use nalgebra::{Rotation2, Rotation3, Vector3, Matrix2, Matrix3};
+    /// # use std::f32;
+    /// let rot = Rotation3::from_axis_angle(&Vector3::z_axis(), f32::consts::FRAC_PI_6);
+    /// let expected = Matrix3::new(0.8660254, -0.5,      0.0,
+    ///                             0.5,       0.8660254, 0.0,
+    ///                             0.0,       0.0,       1.0);
+    /// assert_eq!(*rot.matrix(), expected);
+    ///
+    ///
+    /// let rot = Rotation2::new(f32::consts::FRAC_PI_6);
+    /// let expected = Matrix2::new(0.8660254, -0.5,
+    ///                             0.5,       0.8660254);
+    /// assert_eq!(*rot.matrix(), expected);
+    /// ```
     #[inline]
     pub fn matrix(&self) -> &MatrixN<N, D> {
         &self.matrix
     }
 
     /// A mutable reference to the underlying matrix representation of this rotation.
-    ///
-    /// This is unsafe because this allows the user to replace the matrix by another one that is
-    /// non-square, non-inversible, or non-orthonormal. If one of those properties is broken,
-    /// subsequent method calls may be UB.
     #[inline]
+    #[deprecated(note = "Use `.matrix_mut_unchecked()` instead.")]
     pub unsafe fn matrix_mut(&mut self) -> &mut MatrixN<N, D> {
         &mut self.matrix
     }
 
+    /// A mutable reference to the underlying matrix representation of this rotation.
+    ///
+    /// This is suffixed by "_unchecked" because this allows the user to replace the matrix by another one that is
+    /// non-square, non-inversible, or non-orthonormal. If one of those properties is broken,
+    /// subsequent method calls may be UB.
+    #[inline]
+    pub fn matrix_mut_unchecked(&mut self) -> &mut MatrixN<N, D> {
+        &mut self.matrix
+    }
+
     /// Unwraps the underlying matrix.
+    ///
+    /// # Example
+    /// ```
+    /// # use nalgebra::{Rotation2, Rotation3, Vector3, Matrix2, Matrix3};
+    /// # use std::f32;
+    /// let rot = Rotation3::from_axis_angle(&Vector3::z_axis(), f32::consts::FRAC_PI_6);
+    /// let mat = rot.unwrap();
+    /// let expected = Matrix3::new(0.8660254, -0.5,      0.0,
+    ///                             0.5,       0.8660254, 0.0,
+    ///                             0.0,       0.0,       1.0);
+    /// assert_eq!(mat, expected);
+    ///
+    ///
+    /// let rot = Rotation2::new(f32::consts::FRAC_PI_6);
+    /// let mat = rot.unwrap();
+    /// let expected = Matrix2::new(0.8660254, -0.5,
+    ///                             0.5,       0.8660254);
+    /// assert_eq!(mat, expected);
+    /// ```
     #[inline]
     pub fn unwrap(self) -> MatrixN<N, D> {
         self.matrix
     }
 
     /// Converts this rotation into its equivalent homogeneous transformation matrix.
+    ///
+    /// This is the same as `self.into()`.
+    ///
+    /// # Example
+    /// ```
+    /// # use nalgebra::{Rotation2, Rotation3, Vector3, Matrix2, Matrix3, Matrix4};
+    /// # use std::f32;
+    /// let rot = Rotation3::from_axis_angle(&Vector3::z_axis(), f32::consts::FRAC_PI_6);
+    /// let expected = Matrix4::new(0.8660254, -0.5,      0.0, 0.0,
+    ///                             0.5,       0.8660254, 0.0, 0.0,
+    ///                             0.0,       0.0,       1.0, 0.0,
+    ///                             0.0,       0.0,       0.0, 1.0);
+    /// assert_eq!(rot.to_homogeneous(), expected);
+    ///
+    ///
+    /// let rot = Rotation2::new(f32::consts::FRAC_PI_6);
+    /// let expected = Matrix3::new(0.8660254, -0.5,      0.0,
+    ///                             0.5,       0.8660254, 0.0,
+    ///                             0.0,       0.0,       1.0);
+    /// assert_eq!(rot.to_homogeneous(), expected);
+    /// ```
     #[inline]
     pub fn to_homogeneous(&self) -> MatrixN<N, DimNameSum<D, U1>>
     where
@@ -145,6 +210,25 @@ where DefaultAllocator: Allocator<N, D, D>
     /// Creates a new rotation from the given square matrix.
     ///
     /// The matrix squareness is checked but not its orthonormality.
+    ///
+    /// # Example
+    /// ```
+    /// # use nalgebra::{Rotation2, Rotation3, Matrix2, Matrix3};
+    /// # use std::f32;
+    /// let mat = Matrix3::new(0.8660254, -0.5,      0.0,
+    ///                        0.5,       0.8660254, 0.0,
+    ///                        0.0,       0.0,       1.0);
+    /// let rot = Rotation3::from_matrix_unchecked(mat);
+    ///
+    /// assert_eq!(*rot.matrix(), mat);
+    ///
+    ///
+    /// let mat = Matrix2::new(0.8660254, -0.5,
+    ///                        0.5,       0.8660254);
+    /// let rot = Rotation2::from_matrix_unchecked(mat);
+    ///
+    /// assert_eq!(*rot.matrix(), mat);
+    /// ```
     #[inline]
     pub fn from_matrix_unchecked(matrix: MatrixN<N, D>) -> Rotation<N, D> {
         assert!(
@@ -162,6 +246,22 @@ where DefaultAllocator: Allocator<N, D, D>
     }
 
     /// Inverts `self`.
+    ///
+    /// # Example
+    /// ```
+    /// # #[macro_use] extern crate approx;
+    /// # extern crate nalgebra;
+    /// # use nalgebra::{Rotation2, Rotation3, Vector3};
+    /// let rot = Rotation3::new(Vector3::new(1.0, 2.0, 3.0));
+    /// let inv = rot.inverse();
+    /// assert_relative_eq!(rot * inv, Rotation3::identity(), epsilon = 1.0e-6);
+    /// assert_relative_eq!(inv * rot, Rotation3::identity(), epsilon = 1.0e-6);
+    ///
+    /// let rot = Rotation2::new(1.2);
+    /// let inv = rot.inverse();
+    /// assert_relative_eq!(rot * inv, Rotation2::identity(), epsilon = 1.0e-6);
+    /// assert_relative_eq!(inv * rot, Rotation2::identity(), epsilon = 1.0e-6);
+    /// ```
     #[inline]
     pub fn inverse(&self) -> Rotation<N, D> {
         self.transpose()

src/geometry/rotation_ops.rs

@@ -138,16 +138,16 @@ md_assign_impl_all!(
     MulAssign, mul_assign;
     (D, D), (D, D) for D: DimName;
     self: Rotation<N, D>, right: Rotation<N, D>;
-    [val] => unsafe { self.matrix_mut().mul_assign(right.unwrap()) };
+    [val] => self.matrix_mut_unchecked().mul_assign(right.unwrap());
-    [ref] => unsafe { self.matrix_mut().mul_assign(right.matrix()) };
+    [ref] => self.matrix_mut_unchecked().mul_assign(right.matrix());
 );
 
 md_assign_impl_all!(
     DivAssign, div_assign;
     (D, D), (D, D) for D: DimName;
     self: Rotation<N, D>, right: Rotation<N, D>;
-    [val] => unsafe { self.matrix_mut().mul_assign(right.inverse().unwrap()) };
+    [val] => self.matrix_mut_unchecked().mul_assign(right.inverse().unwrap());
-    [ref] => unsafe { self.matrix_mut().mul_assign(right.inverse().matrix()) };
+    [ref] => self.matrix_mut_unchecked().mul_assign(right.inverse().matrix());
 );
 
 // Matrix *= Rotation