Clarify the docs about which Euler angle convention is used.

src/base/cg.rs

@@ -152,7 +152,23 @@ impl<T: RealField> Matrix4<T> {
 
     /// Creates a new rotation from Euler angles.
     ///
-    /// The primitive rotations are applied in order: 1 roll − 2 pitch − 3 yaw.
+    /// The angles are interpreted as extrinsic rotations around the X, Y and Z axis.
+    /// These angles are also often called roll, pitch and yaw.
+    ///
+    /// The returned rotation could also be constructed in the following manner:
+    ///
+    /// ```
+    /// # use nalgebra::{Matrix4, Vector3};
+    /// # use approx::assert_relative_eq;
+    /// # let angle_x: f32 = 0.5;
+    /// # let angle_y: f32 = 1.2;
+    /// # let angle_z: f32 = 2.3;
+    /// let rotation = Matrix4::from_euler_angles(angle_x, angle_y, angle_z);
+    /// let manually_combined = Matrix4::from_axis_angle(&Vector3::z_axis(), angle_z)
+    ///   * Matrix4::from_axis_angle(&Vector3::y_axis(), angle_y)
+    ///   * Matrix4::from_axis_angle(&Vector3::x_axis(), angle_x);
+    /// assert_relative_eq!(manually_combined, rotation, epsilon = 1e6);
+    /// ```
     pub fn from_euler_angles(roll: T, pitch: T, yaw: T) -> Self {
         Rotation3::from_euler_angles(roll, pitch, yaw).to_homogeneous()
     }

src/geometry/quaternion.rs

@@ -1466,9 +1466,24 @@ where
 
     /// Converts this unit quaternion into its equivalent Euler angles.
     ///
-    /// The angles are produced in the form (roll, pitch, yaw).
+    /// The returned angles are extrinsic rotations around the X, Y and Z axis.
+    /// These angles are also often called roll, pitch and yaw.
+    ///
+    /// To get the original rotation back from the individual angles, you would combine them in the following manner:
+    ///
+    /// ```
+    /// # #![allow(deprecated)]
+    /// # use nalgebra::{UnitQuaternion, Vector3};
+    /// # use approx::assert_relative_eq;
+    /// # let rotation = UnitQuaternion::from_euler_angles(0.5_f32, 1.2, 2.3);
+    /// let angles = rotation.to_euler_angles();
+    /// let recombined = UnitQuaternion::from_axis_angle(&Vector3::z_axis(), angles.2)
+    ///   * UnitQuaternion::from_axis_angle(&Vector3::y_axis(), angles.1)
+    ///   * UnitQuaternion::from_axis_angle(&Vector3::x_axis(), angles.0);
+    /// assert_relative_eq!(recombined, rotation, epsilon = 1e-6);
+    /// ```
     #[inline]
-    #[deprecated(note = "This is renamed to use `.euler_angles()`.")]
+    #[deprecated(note = "This is renamed to `.euler_angles()`.")]
     pub fn to_euler_angles(self) -> (T, T, T)
     where
         T: RealField,
@@ -1478,17 +1493,31 @@ where
 
     /// Retrieves the euler angles corresponding to this unit quaternion.
     ///
-    /// The angles are produced in the form (roll, pitch, yaw).
+    /// The returned angles are extrinsic rotations around the X, Y and Z axis.
+    /// These angles are also often called roll, pitch and yaw.
+    ///
+    /// To get the original rotation back from the individual angles, you would combine them in the following manner:
+    ///
+    /// ```
+    /// # use nalgebra::{UnitQuaternion, Vector3};
+    /// # use approx::assert_relative_eq;
+    /// # let rotation = UnitQuaternion::from_euler_angles(0.5_f32, 1.2, 2.3);
+    /// let angles = rotation.euler_angles();
+    /// let recombined = UnitQuaternion::from_axis_angle(&Vector3::z_axis(), angles.2)
+    ///   * UnitQuaternion::from_axis_angle(&Vector3::y_axis(), angles.1)
+    ///   * UnitQuaternion::from_axis_angle(&Vector3::x_axis(), angles.0);
+    /// assert_relative_eq!(recombined, rotation, epsilon = 1e-6);
+    /// ```
     ///
     /// # Example
     /// ```
     /// # #[macro_use] extern crate approx;
     /// # use nalgebra::UnitQuaternion;
     /// let rot = UnitQuaternion::from_euler_angles(0.1, 0.2, 0.3);
-    /// let euler = rot.euler_angles();
-    /// assert_relative_eq!(euler.0, 0.1, epsilon = 1.0e-6);
-    /// assert_relative_eq!(euler.1, 0.2, epsilon = 1.0e-6);
-    /// assert_relative_eq!(euler.2, 0.3, epsilon = 1.0e-6);
+    /// let (x, y, z) = rot.euler_angles();
+    /// assert_relative_eq!(x, 0.1, epsilon = 1.0e-6);
+    /// assert_relative_eq!(y, 0.2, epsilon = 1.0e-6);
+    /// assert_relative_eq!(z, 0.3, epsilon = 1.0e-6);
     /// ```
     #[inline]
     #[must_use]

src/geometry/quaternion_construction.rs

@@ -282,7 +282,23 @@ where
 
     /// Creates a new unit quaternion from Euler angles.
     ///
-    /// The primitive rotations are applied in order: 1 roll − 2 pitch − 3 yaw.
+    /// The angles are interpreted as extrinsic rotations around the X, Y and Z axis.
+    /// These angles are also often called roll, pitch and yaw.
+    ///
+    /// The returned rotation could also be constructed in the following manner:
+    ///
+    /// ```
+    /// # use nalgebra::{UnitQuaternion, Vector3};
+    /// # use approx::assert_relative_eq;
+    /// # let angle_x: f32 = 0.5;
+    /// # let angle_y: f32 = 1.2;
+    /// # let angle_z: f32 = 2.3;
+    /// let rotation = UnitQuaternion::from_euler_angles(angle_x, angle_y, angle_z);
+    /// let manually_combined = UnitQuaternion::from_axis_angle(&Vector3::z_axis(), angle_z)
+    ///   * UnitQuaternion::from_axis_angle(&Vector3::y_axis(), angle_y)
+    ///   * UnitQuaternion::from_axis_angle(&Vector3::x_axis(), angle_x);
+    /// assert_relative_eq!(manually_combined, rotation, epsilon = 1e6);
+    /// ```
     ///
     /// # Example
     /// ```

src/geometry/rotation_specialization.rs

@@ -417,7 +417,23 @@ where
 
     /// Creates a new rotation from Euler angles.
     ///
-    /// The primitive rotations are applied in order: 1 roll − 2 pitch − 3 yaw.
+    /// The angles are interpreted as extrinsic rotations around the X, Y and Z axis.
+    /// These angles are also often called roll, pitch and yaw.
+    ///
+    /// The returned rotation could also be constructed in the following manner:
+    ///
+    /// ```
+    /// # use nalgebra::{Rotation3, Vector3};
+    /// # use approx::assert_relative_eq;
+    /// # let angle_x: f32 = 0.5;
+    /// # let angle_y: f32 = 1.2;
+    /// # let angle_z: f32 = 2.3;
+    /// let rotation = Rotation3::from_euler_angles(angle_x, angle_y, angle_z);
+    /// let manually_combined = Rotation3::from_axis_angle(&Vector3::z_axis(), angle_z)
+    ///   * Rotation3::from_axis_angle(&Vector3::y_axis(), angle_y)
+    ///   * Rotation3::from_axis_angle(&Vector3::x_axis(), angle_x);
+    /// assert_relative_eq!(manually_combined, rotation, epsilon = 1e6);
+    /// ```
     ///
     /// # Example
     /// ```
@@ -934,8 +950,23 @@ impl<T: SimdRealField> Rotation3<T> {
 
     /// Creates Euler angles from a rotation.
     ///
-    /// The angles are produced in the form (roll, pitch, yaw).
-    #[deprecated(note = "This is renamed to use `.euler_angles()`.")]
+    /// The returned angles are extrinsic rotations around the X, Y and Z axis.
+    /// These angles are also often called roll, pitch and yaw.
+    ///
+    /// To get the original rotation back from the individual angles, you would combine them in the following manner:
+    ///
+    /// ```
+    /// # #![allow(deprecated)]
+    /// # use nalgebra::{Rotation3, Vector3};
+    /// # use approx::assert_relative_eq;
+    /// # let rotation = Rotation3::from_euler_angles(0.5_f32, 1.2, 2.3);
+    /// let angles = rotation.to_euler_angles();
+    /// let recombined = Rotation3::from_axis_angle(&Vector3::z_axis(), angles.2)
+    ///   * Rotation3::from_axis_angle(&Vector3::y_axis(), angles.1)
+    ///   * Rotation3::from_axis_angle(&Vector3::x_axis(), angles.0);
+    /// assert_relative_eq!(recombined, rotation, epsilon = 1e-6);
+    /// ```
+    #[deprecated(note = "This is renamed to `.euler_angles()`.")]
     pub fn to_euler_angles(self) -> (T, T, T)
     where
         T: RealField,
@@ -945,7 +976,21 @@ impl<T: SimdRealField> Rotation3<T> {
 
     /// Euler angles corresponding to this rotation from a rotation.
     ///
-    /// The angles are produced in the form (roll, pitch, yaw).
+    /// The returned angles are extrinsic rotations around the X, Y and Z axis.
+    /// These angles are also often called roll, pitch and yaw.
+    ///
+    /// To get the original rotation back from the individual angles, you would combine them in the following manner:
+    ///
+    /// ```
+    /// # use nalgebra::{Rotation3, Vector3};
+    /// # use approx::assert_relative_eq;
+    /// # let rotation = Rotation3::from_euler_angles(0.5_f32, 1.2, 2.3);
+    /// let angles = rotation.euler_angles();
+    /// let recombined = Rotation3::from_axis_angle(&Vector3::z_axis(), angles.2)
+    ///   * Rotation3::from_axis_angle(&Vector3::y_axis(), angles.1)
+    ///   * Rotation3::from_axis_angle(&Vector3::x_axis(), angles.0);
+    /// assert_relative_eq!(recombined, rotation, epsilon = 1e-6);
+    /// ```
     ///
     /// # Example
     /// ```