From a7551efd0231f9e0bd466429897972fb320a7e75 Mon Sep 17 00:00:00 2001
From: Aaron Schaefer <aaron@elasticdog.com>
Date: Mon, 17 Nov 2008 21:12:10 -0500
Subject: [PATCH] Add documentation for math.quaternions

---
 .../math/quaternions/quaternions-docs.factor  | 46 +++++++++++++++++++
 extra/math/quaternions/quaternions.factor     | 35 +++++---------
 2 files changed, 58 insertions(+), 23 deletions(-)
 create mode 100644 extra/math/quaternions/quaternions-docs.factor

diff --git a/extra/math/quaternions/quaternions-docs.factor b/extra/math/quaternions/quaternions-docs.factor
new file mode 100644
index 0000000000..bb34ec8da2
--- /dev/null
+++ b/extra/math/quaternions/quaternions-docs.factor
@@ -0,0 +1,46 @@
+USING: help.markup help.syntax math math.vectors vectors ;
+IN: math.quaternions
+
+HELP: q*
+{ $values { "u" "a quaternion" } { "v" "a quaternion" } { "u*v" "a quaternion" } }
+{ $description "Multiply quaternions." }
+{ $examples { $example "USING: math.quaternions prettyprint ;" "{ C{ 0 1 } 0 } { 0 1 } q* ." "{ 0 C{ 0 1 } }" } } ;
+
+HELP: qconjugate
+{ $values { "u" "a quaternion" } { "u'" "a quaternion" } }
+{ $description "Quaternion conjugate." } ;
+
+HELP: qrecip
+{ $values { "u" "a quaternion" } { "1/u" "a quaternion" } }
+{ $description "Quaternion inverse." } ;
+
+HELP: q/
+{ $values { "u" "a quaternion" } { "v" "a quaternion" } { "u/v" "a quaternion" } }
+{ $description "Divide quaternions." }
+{ $examples { $example "USING: math.quaternions prettyprint ;" "{ 0 C{ 0 1 } } { 0 1 } q/ ." "{ C{ 0 1 } 0 }" } } ;
+
+HELP: q*n
+{ $values { "q" "a quaternion" } { "n" number } { "q" "a quaternion" } }
+{ $description "Multiplies each element of " { $snippet "q" } " by " { $snippet "n" } "." }
+{ $notes "You will get the wrong result if you try to multiply a quaternion by a complex number on the right using " { $link v*n } ". Use this word instead."
+    $nl "Note that " { $link v*n } " with a quaternion and a real is okay." } ;
+
+HELP: c>q
+{ $values { "c" number } { "q" "a quaternion" } }
+{ $description "Turn a complex number into a quaternion." }
+{ $examples { $example "USING: math.quaternions prettyprint ;" "C{ 0 1 } c>q ." "{ C{ 0 1 } 0 }" } } ;
+
+HELP: v>q
+{ $values { "v" vector } { "q" "a quaternion" } }
+{ $description "Turn a 3-vector into a quaternion with real part 0." }
+{ $examples { $example "USING: math.quaternions prettyprint ;" "{ 1 0 0 } v>q ." "{ C{ 0 1 } 0 }" } } ;
+
+HELP: q>v
+{ $values { "q" "a quaternion" } { "v" vector } }
+{ $description "Get the vector part of a quaternion, discarding the real part." }
+{ $examples { $example "USING: math.quaternions prettyprint ;" "{ C{ 0 1 } 0 } q>v ." "{ 1 0 0 }" } } ;
+
+HELP: euler
+{ $values { "phi" number } { "theta" number } { "psi" number } { "q" "a quaternion" } }
+{ $description "Convert a rotation given by Euler angles (phi, theta, and psi) to a quaternion." } ;
+
diff --git a/extra/math/quaternions/quaternions.factor b/extra/math/quaternions/quaternions.factor
index ffc0fcc9f7..bb0d025dc6 100755
--- a/extra/math/quaternions/quaternions.factor
+++ b/extra/math/quaternions/quaternions.factor
@@ -1,15 +1,13 @@
 ! Copyright (C) 2005, 2007 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
-
-! Everybody's favorite non-commutative skew field, the
-! quaternions!
-
-! Quaternions are represented as pairs of complex numbers,
-! using the identity: (a+bi)+(c+di)j = a+bi+cj+dk.
-USING: arrays kernel math math.vectors math.functions
-arrays sequences ;
+USING: arrays kernel math math.functions math.vectors sequences ;
 IN: math.quaternions
 
+! Everybody's favorite non-commutative skew field, the quaternions!
+
+! Quaternions are represented as pairs of complex numbers, using the
+! identity: (a+bi)+(c+di)j = a+bi+cj+dk.
+
 <PRIVATE
 
 : ** conjugate * ; inline
@@ -23,39 +21,27 @@ IN: math.quaternions
 PRIVATE>
 
 : q* ( u v -- u*v )
-    #! Multiply quaternions.
     [ q*a ] [ q*b ] 2bi 2array ;
 
 : qconjugate ( u -- u' )
-    #! Quaternion conjugate.
     first2 [ conjugate ] [ neg  ] bi* 2array ;
 
 : qrecip ( u -- 1/u )
-    #! Quaternion inverse.
     qconjugate dup norm-sq v/n ;
 
 : q/ ( u v -- u/v )
-    #! Divide quaternions.
     qrecip q* ;
 
 : q*n ( q n -- q )
-    #! Note: you will get the wrong result if you try to
-    #! multiply a quaternion by a complex number on the right
-    #! using v*n. Use this word instead. Note that v*n with a
-    #! quaternion and a real is okay.
     conjugate v*n ;
 
 : c>q ( c -- q )
-    #! Turn a complex number into a quaternion.
     0 2array ;
 
 : v>q ( v -- q )
-    #! Turn a 3-vector into a quaternion with real part 0.
     first3 rect> [ 0 swap rect> ] dip 2array ;
 
 : q>v ( q -- v )
-    #! Get the vector part of a quaternion, discarding the real
-    #! part.
     first2 [ imaginary-part ] dip >rect 3array ;
 
 ! Zero
@@ -67,11 +53,14 @@ PRIVATE>
 : qj { 0 1 } ;
 : qk { 0 C{ 0 1 } } ;
 
-! Euler angles -- see
-! http://www.mathworks.com/access/helpdesk/help/toolbox/aeroblks/euleranglestoquaternions.html
+! Euler angles
+
+<PRIVATE
 
 : (euler) ( theta unit -- q )
-    [ -0.5 * dup cos c>q swap sin ] dip n*v v- ;
+    [ -0.5 * [ cos c>q ] [ sin ] bi ] dip n*v v- ;
+
+PRIVATE>
 
 : euler ( phi theta psi -- q )
   [ qi (euler) ] [ qj (euler) ] [ qk (euler) ] tri* q* q* ;