From 46713c920b43354826b954f5a54be85b7bdf86f3 Mon Sep 17 00:00:00 2001
From: Egor Larionov <egor.larionov@gmail.com>
Date: Mon, 10 Aug 2020 17:42:02 -0700
Subject: [PATCH] Update docs of look_* functions

This change clarifies the meaning of the _lh and _rh suffixes.
---
 src/matrix.rs    | 24 ++++++++++++++++--------
 src/rotation.rs  |  1 +
 src/transform.rs | 12 ++++++++----
 3 files changed, 25 insertions(+), 12 deletions(-)

diff --git a/src/matrix.rs b/src/matrix.rs
index f5b7ac6e..52ec07a9 100644
--- a/src/matrix.rs
+++ b/src/matrix.rs
@@ -366,8 +366,10 @@ impl<S: BaseFloat> Matrix4<S> {
         Self::look_to_rh(eye, dir, up)
     }
 
-    /// Create a homogeneous transformation matrix that will cause a vector to point at
-    /// `dir`, using `up` for orientation.
+    /// Creates a homogeneous right-handed look-at transformation matrix.
+    ///
+    /// This matrix will transform a vector to point in `dir` direction, using `up` for orientation
+    /// assuming a right-handed corrdinate system.
     pub fn look_to_rh(eye: Point3<S>, dir: Vector3<S>, up: Vector3<S>) -> Matrix4<S> {
         let f = dir.normalize();
         let s = f.cross(up).normalize();
@@ -382,8 +384,10 @@ impl<S: BaseFloat> Matrix4<S> {
         )
     }
 
-    /// Create a homogeneous transformation matrix that will cause a vector to point at
-    /// `dir`, using `up` for orientation.
+    /// Creates a homogeneous left-handed look-at transformation matrix.
+    ///
+    /// This matrix will transform a vector to point in `dir` direction, using `up` for orientation
+    /// assuming a left-handed corrdinate system.
     pub fn look_to_lh(eye: Point3<S>, dir: Vector3<S>, up: Vector3<S>) -> Matrix4<S> {
         Matrix4::look_to_rh(eye, -dir, up)
     }
@@ -395,14 +399,18 @@ impl<S: BaseFloat> Matrix4<S> {
         Matrix4::look_to_rh(eye, center - eye, up)
     }
 
-    /// Create a homogeneous transformation matrix that will cause a vector to point at
-    /// `center`, using `up` for orientation.
+    /// Creates a homogeneous right-handed look-at transformation matrix.
+    ///
+    /// This matrix will transform a vector to point at `center`, using `up` for orientation
+    /// assuming a right-handed corrdinate system.
     pub fn look_at_rh(eye: Point3<S>, center: Point3<S>, up: Vector3<S>) -> Matrix4<S> {
         Matrix4::look_to_rh(eye, center - eye, up)
     }
 
-    /// Create a homogeneous transformation matrix that will cause a vector to point at
-    /// `center`, using `up` for orientation.
+    /// Creates a homogeneous left-handed look-at transformation matrix.
+    ///
+    /// This matrix will transform a vector to point at `center`, using `up` for orientation
+    /// assuming a left-handed corrdinate system.
     pub fn look_at_lh(eye: Point3<S>, center: Point3<S>, up: Vector3<S>) -> Matrix4<S> {
         Matrix4::look_to_lh(eye, center - eye, up)
     }
diff --git a/src/rotation.rs b/src/rotation.rs
index ecd22dee..933f6e1a 100644
--- a/src/rotation.rs
+++ b/src/rotation.rs
@@ -341,6 +341,7 @@ impl<'a, S: 'a + BaseFloat> iter::Product<&'a Basis3<S>> for Basis3<S> {
 }
 
 impl<S: BaseFloat> Rotation<Point3<S>> for Basis3<S> {
+    /// Construct a look-at view matrix assuming a left-handed coordinate system.
     #[inline]
     fn look_to(dir: Vector3<S>, up: Vector3<S>) -> Basis3<S> {
         Basis3 {
diff --git a/src/transform.rs b/src/transform.rs
index 53a82abe..0ce9fa3d 100644
--- a/src/transform.rs
+++ b/src/transform.rs
@@ -37,12 +37,16 @@ pub trait Transform<P: EuclideanSpace>: Sized {
         Self::look_at_lh(eye, center, up)
     }
 
-    /// Create a transformation that rotates a vector to look at `center` from
-    /// `eye`, using `up` for orientation.
+    /// Creates a right-handed look-at view transform.
+    ///
+    /// This transform rotates a vector to look at `center` from `eye`, using `up` for orientation
+    /// assuming a right-handed coordinate system.
     fn look_at_rh(eye: P, center: P, up: P::Diff) -> Self;
 
-    /// Create a transformation that rotates a vector to look at `center` from
-    /// `eye`, using `up` for orientation.
+    /// Creates a right-handed look-at view transform.
+    ///
+    /// This transform rotates a vector to look at `center` from `eye`, using `up` for orientation
+    /// assuming a left-handed coordinate system.
     fn look_at_lh(eye: P, center: P, up: P::Diff) -> Self;
 
     /// Transform a vector using this transform.