Add more doc strings

src/mathree/angle.cljs

@@ -6,18 +6,18 @@
 ;; 1. degrees
 
 (defn standard-angle-in-degrees
-  ";; standardAngle (angle) → number
+  "standardAngle (angle) → number
    Normalizes an angle to be in range [0-360). Angles outside this range will be normalized to be the equivalent angle with that range."
   [angle]
   (gmath/standardAngle angle))
 
 (defn to-degrees
-  ";; toDegrees (angleRadians) → number"
+  "toDegrees (angleRadians) → number"
   [angle-in-radians]
   (gmath/toDegrees angle-in-radians))
 
 (defn parse-degrees 
-  " convert angle in degrees to parsed format of degrees, minutes and seconds"
+  "convert angle in degrees to parsed format of degrees, minutes and seconds"
   [angle-in-degrees]
   (let [degree (int angle-in-degrees)
         rem-degree (rem angle-in-degrees 1)
@@ -29,7 +29,7 @@
      :seconds second}))
 
 (defn calculate-degrees 
-  " convert parsed format to angle in degrees"
+  "convert parsed format to angle in degrees"
   [parsed-degrees]
   (let [{:keys [degrees minutes seconds]} parsed-degrees]
     (+ degrees
@@ -40,13 +40,13 @@
 ;; 2. radians
 
 (defn standard-angle-in-radians
-  ";; standardAngleInRadians (angle) → number
+  "standardAngleInRadians (angle) → number
    Normalizes an angle to be in range [0-2*PI). Angles outside this range will be normalized to be the equivalent angle with that range."
   [angle-in-radians]
   (gmath/standardAngleInRadians angle-in-radians))
 
 (defn to-radians
-  ";; toRadians (angleDegrees) → number"
+  "toRadians (angleDegrees) → number"
   [angle-in-degree]
   (gmath/toRadians angle-in-degree))
 

src/mathree/arithmetic.cljs

@@ -21,7 +21,9 @@
    (every? (fn [n] (almost-equals n 0.0 opt_tolerance)) (map - seqa seqb))))
 
 
-(defn rand-sign []
+(defn rand-sign 
+  "rand of -1 or 1"
+  []
   (if (< (rand) 0.5) -1 1))
 
 (defn log

src/mathree/euler.cljs

@@ -4,10 +4,9 @@
    ["three" :as three]))
 
 (defprotocol IEuler
-  (clone' [r])
-  (equals [r1 r2])
-  (reorder [r order])
-  )
+  (clone' [r] "Returns a new Euler with the same parameters as this one.")
+  (equals [r1 r2] "Checks for strict equality of this euler and euler.")
+  (reorder [r order] "Resets the euler angle with a new order by creating a quaternion from this euler angle and then setting this euler angle with the quaternion and the new order."))
 
 
 (extend-type three/Euler
@@ -51,19 +50,33 @@
 
 
 (defn euler
+  "Constructor
+Euler( x : Float, y : Float, z : Float, order : String )
+x - (optional) the angle of the x axis in radians. Default is 0.
+y - (optional) the angle of the y axis in radians. Default is 0.
+z - (optional) the angle of the z axis in radians. Default is 0.
+order - (optional) a string representing the order that the rotations are applied, defaults to 'XYZ' (must be upper case).
+"
   ([] (three/Euler.))
   ([order] (three/Euler. 0 0 0 order))
   ([x y z] (three/Euler. x y z))
   ([x y z order] (three/Euler. x y z order)))
 
+
 (defn from-seq
+  "convert a seq of 3 elements to vector3, default order id XYZ.
+   or give order as second argument
+   "
   ([sq]
    (from-seq sq "XYZ"))
   ([sq order]
    (let [[x y z] sq]
      (euler x y z order))))
 
 (defn from-quaternion
+  "q - a normalized quaternion.
+   order - (optional) a string representing the order that the rotations are applied.
+   Sets the angles of this euler transform from a normalized quaternion based on the orientation specified by order."
   ([q]
    (from-quaternion q "XYZ"))
   ([q order]

src/mathree/math_utils.cljs

@@ -21,131 +21,130 @@
   (j/call math-utils :degToRad degree))
 
 (defn euclidean-modulo
-  ";; .euclideanModulo ( n : Integer, m : Integer ) : Integer
-   ;; n, m - Integers
-   ;; Computes the Euclidean modulo of m % n, that is:
-   ;; ( ( n % m ) + m ) % m "
+  ".euclideanModulo ( n : Integer, m : Integer ) : Integer
+   n, m - Integers
+   Computes the Euclidean modulo of m % n, that is:
+   ( ( n % m ) + m ) % m "
   [n m]
   (j/call math-utils .euclideanModulo n m))
 
 (defn generate-UUID
-  ";; .generateUUID ( ) : UUID
-   ;; Generate a UUID (universally unique identifier)."
+  ".generateUUID ( ) : UUID
+   Generate a UUID (universally unique identifier)."
   []
   (j/call math-utils .generateUUID))
 
 (defn is-power-of-two
-  ";; .isPowerOfTwo ( n : Number ) : Boolean
-   ;; Return true if n is a power of 2."
+  ".isPowerOfTwo ( n : Number ) : Boolean
+   Return true if n is a power of 2."
   [n]
   (j/call math-utils .isPowerOfTwo n))
 
 (defn inverse-lerp
-  ";; .inverseLerp ( x : Float, y : Float, value : Float ) : Float
-   ;; x - Start point.
-   ;; y - End point.
-   ;; value - A value between start and end.
-   ;; Returns the percentage in the closed interval [0, 1] of the given value between the start and end point.
+  ".inverseLerp ( x : Float, y : Float, value : Float ) : Float
+   x - Start point.
+   y - End point.
+   value - A value between start and end.
+   Returns the percentage in the closed interval [0, 1] of the given value between the start and end point.
    "
   [x y value]
   (j/call math-utils .inverseLerp x y value))
 
 (defn lerp
-  "
-;; .lerp ( x : Float, y : Float, t : Float ) : Float
-;; x - Start point.
-;; y - End point.
-;; t - interpolation factor in the closed interval [0, 1].
+  ".lerp ( x : Float, y : Float, t : Float ) : Float
+x - Start point.
+y - End point.
+t - interpolation factor in the closed interval [0, 1].
 
-;; Returns a value linearly interpolated from two known points based on the given interval - t = 0 will return x and t = 1 will return y.
+Returns a value linearly interpolated from two known points based on the given interval - t = 0 will return x and t = 1 will return y.
 "
   [x y t]
   (j/call math-utils .lerp x y t))
 
 
 (defn damp
-  ";; .damp ( x : Float, y : Float, lambda : Float, dt : Float ) : Float
-;; x - Current point.
-;; y - Target point.
-;; lambda - A higher lambda value will make the movement more sudden, and a lower value will make the movement more gradual.
-;; dt - Delta time in seconds.
+  ".damp ( x : Float, y : Float, lambda : Float, dt : Float ) : Float
+x - Current point.
+y - Target point.
+lambda - A higher lambda value will make the movement more sudden, and a lower value will make the movement more gradual.
+dt - Delta time in seconds.
 
-;; Smoothly interpolate a number from x toward y in a spring-like manner using the dt to maintain frame rate independent movement. For details, see Frame rate independent damping using lerp.
+Smoothly interpolate a number from x toward y in a spring-like manner using the dt to maintain frame rate independent movement. For details, see Frame rate independent damping using lerp.
 "
   [x y lambda dt]
   (j/call math-utils .damp x y lambda dt))
 
 (defn map-linear
-  ";; .mapLinear ( x : Float, a1 : Float, a2 : Float, b1 : Float, b2 : Float ) : Float
-;; x — Value to be mapped.
-;; a1 — Minimum value for range A.
-;; a2 — Maximum value for range A.
-;; b1 — Minimum value for range B.
-;; b2 — Maximum value for range B.
-
-;; Linear mapping of x from range [a1, a2] to range [b1, b2].
+  ".mapLinear ( x : Float, a1 : Float, a2 : Float, b1 : Float, b2 : Float ) : Float
+x — Value to be mapped.
+a1 — Minimum value for range A.
+a2 — Maximum value for range A.
+b1 — Minimum value for range B.
+b2 — Maximum value for range B.
+
+Linear mapping of x from range [a1, a2] to range [b1, b2].
 "
   [x a1 a2 b1 b2]
   (j/call math-utils :mapLinear x a1 a2 b1 b2))
 
 
 (defn pingpong
-  ";; .pingpong ( x : Float, length : Float ) : Float
-;; x — The value to pingpong.
-;; length — The positive value the function will pingpong to. Default is 1.
+  ".pingpong ( x : Float, length : Float ) : Float
+x — The value to pingpong.
+length — The positive value the function will pingpong to. Default is 1.
 
-;; Returns a value that alternates between 0 and length : Float.
+Returns a value that alternates between 0 and length : Float.
 "
   [x length]
   (j/call math-utils :pingpong x length))
 
 
 (defn ceil-power-of-two
-  ";; .ceilPowerOfTwo ( n : Number ) : Integer
-;; Returns the smallest power of 2 that is greater than or equal to n.
+  ".ceilPowerOfTwo ( n : Number ) : Integer
+Returns the smallest power of 2 that is greater than or equal to n.
 "
   [n]
   (j/call math-utils .ceilPowerOfTwo n))
 
 (defn floor-power-of-two
-  ";; .floorPowerOfTwo ( n : Number ) : Integer
-;; Returns the largest power of 2 that is less than or equal to n.
+  ".floorPowerOfTwo ( n : Number ) : Integer
+Returns the largest power of 2 that is less than or equal to n.
 "
   [n]
   (j/call math-utils .floorPowerOfTwo n))
 
 
 (defn rad-to-deg
-  ";; .radToDeg ( radians : Float ) : Float
-   ;; Converts radians to degrees."
+  ".radToDeg ( radians : Float ) : Float
+   Converts radians to degrees."
   [radians]
   (j/call math-utils .radToDeg radians))
 
 
 (defn rand-float
-  ";; .randFloat ( low : Float, high : Float ) : Float
-   ;; Random float in the interval [low, high]."
+  ".randFloat ( low : Float, high : Float ) : Float
+   Random float in the interval [low, high]."
   [low high]
   (j/call math-utils .randFloat low high))
 
 (defn rand-float-spread
-  ";; .randFloatSpread ( range : Float ) : Float
-;; Random float in the interval [- range / 2, range / 2].
+  ".randFloatSpread ( range : Float ) : Float
+Random float in the interval [- range / 2, range / 2].
 "
   [range]
   (j/call math-utils .randFloatSpread range))
 
 (defn rand-integer
-  ";; .randInt ( low : Integer, high : Integer ) : Integer
-;; Random integer in the interval [low, high].
+  ".randInt ( low : Integer, high : Integer ) : Integer
+Random integer in the interval [low, high].
 "
   [low high]
   (j/call math-utils .randInt low high))
 
 (defn seeded-random
   "
-;; .seededRandom ( seed : Integer ) : Float
-;; Deterministic pseudo-random float in the interval [0, 1]. The integer seed is optional.
+.seededRandom ( seed : Integer ) : Float
+Deterministic pseudo-random float in the interval [0, 1]. The integer seed is optional.
 "
   ([]
    (j/call math-utils .seededRandom))
@@ -154,41 +153,30 @@
 
 
 (defn smooth-step
-  ";; .smoothstep ( x : Float, min : Float, max : Float ) : Float
-;; x - The value to evaluate based on its position between min and max.
-;; min - Any x value below min will be 0.
-;; max - Any x value above max will be 1.
+  ".smoothstep ( x : Float, min : Float, max : Float ) : Float
+x - The value to evaluate based on its position between min and max.
+min - Any x value below min will be 0.
+max - Any x value above max will be 1.
 
-;; Returns a value between 0-1 that represents the percentage that x has moved between min and max, but smoothed or slowed down the closer X is to the min and max.
-;; See Smoothstep for details.
+Returns a value between 0-1 that represents the percentage that x has moved between min and max, but smoothed or slowed down the closer X is to the min and max.
+See Smoothstep for details.
 "
   [x min max]
   (j/call math-utils .smoothstep x min max))
 
 
 (defn smoother-step
-  ";; .smootherstep ( x : Float, min : Float, max : Float ) : Float
-;; x - The value to evaluate based on its position between min and max.
-;; min - Any x value below min will be 0.
-;; max - Any x value above max will be 1.
+  ".smootherstep ( x : Float, min : Float, max : Float ) : Float
+x - The value to evaluate based on its position between min and max.
+min - Any x value below min will be 0.
+max - Any x value above max will be 1.
 
-;; Returns a value between 0-1. A variation on smoothstep that has zero 1st and 2nd order derivatives at x=0 and x=1.
+Returns a value between 0-1. A variation on smoothstep that has zero 1st and 2nd order derivatives at x=0 and x=1.
 "
   [x min max]
   (j/call math-utils .smootherstep x min max))
 
 
-;; .setQuaternionFromProperEuler ( q : Quaternion, a : Float, b : Float, c : Float, order : String ) : null
-;; q - the quaternion to be set
-;; a - the rotation applied to the first axis, in radians
-;; b - the rotation applied to the second axis, in radians
-;; c - the rotation applied to the third axis, in radians
-;; order - a string specifying the axes order: 'XYX', 'XZX', 'YXY', 'YZY', 'ZXZ', or 'ZYZ'
-
-;; Sets quaternion q from the intrinsic Proper Euler Angles defined by angles a, b, and c, and order order.
-;; Rotations are applied to the axes in the order specified by order: rotation by angle a is applied first, then by angle b, then by angle c. Angles are in radians.
-
-
 
 
 (comment
@@ -207,5 +195,4 @@
 
   (rand-float 0 34)
 
-;;   
   )