From e245f24ca15fa15a060aa2615e44e4f71d2c33b7 Mon Sep 17 00:00:00 2001
From: David Briscoe <idbrii@gmail.com>
Date: Sat, 26 Mar 2022 16:49:39 -0700
Subject: [PATCH] vec: Add more comments to clarify operations

Clarify order and behaviour so you can use these functions without
looking up the meaning of vector arithmetic.
---
 modules/vec2.lua | 8 +++++++-
 modules/vec3.lua | 7 +++++++
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/modules/vec2.lua b/modules/vec2.lua
index e4d7e3c..bd26f78 100644
--- a/modules/vec2.lua
+++ b/modules/vec2.lua
@@ -97,6 +97,8 @@ function vec2.add(a, b)
 end
 
 --- Subtract one vector from another.
+-- Order: If a and b are positions, computes the direction and distance from b
+-- to a.
 -- @tparam vec2 a Left hand operand
 -- @tparam vec2 b Right hand operand
 -- @treturn vec2 out
@@ -108,6 +110,7 @@ function vec2.sub(a, b)
 end
 
 --- Multiply a vector by another vector.
+-- Component-size multiplication not matrix multiplication.
 -- @tparam vec2 a Left hand operand
 -- @tparam vec2 b Right hand operand
 -- @treturn vec2 out
@@ -119,6 +122,7 @@ function vec2.mul(a, b)
 end
 
 --- Divide a vector by another vector.
+-- Component-size inv multiplication. Like a non-uniform scale().
 -- @tparam vec2 a Left hand operand
 -- @tparam vec2 b Right hand operand
 -- @treturn vec2 out
@@ -148,6 +152,8 @@ function vec2.trim(a, len)
 end
 
 --- Get the cross product of two vectors.
+-- Order: Positive if a is clockwise from b. Magnitude is the area spanned by
+-- the parallelograms that a and b span.
 -- @tparam vec2 a Left hand operand
 -- @tparam vec2 b Right hand operand
 -- @treturn number magnitude
@@ -333,7 +339,7 @@ end
 
 -- Round all components to nearest int (or other precision).
 -- @tparam vec2 a Vector to round.
--- @tparam precision Digits after the decimal (round numebr if unspecified)
+-- @tparam precision Digits after the decimal (integer if unspecified)
 -- @treturn vec2 Rounded vector
 function vec2.round(a, precision)
 	return vec2.new(private.round(a.x, precision), private.round(a.y, precision))
diff --git a/modules/vec3.lua b/modules/vec3.lua
index 032b596..a0c3ca4 100644
--- a/modules/vec3.lua
+++ b/modules/vec3.lua
@@ -93,6 +93,8 @@ function vec3.add(a, b)
 end
 
 --- Subtract one vector from another.
+-- Order: If a and b are positions, computes the direction and distance from b
+-- to a.
 -- @tparam vec3 a Left hand operand
 -- @tparam vec3 b Right hand operand
 -- @treturn vec3 out
@@ -105,6 +107,7 @@ function vec3.sub(a, b)
 end
 
 --- Multiply a vector by another vectorr.
+-- Component-size multiplication not matrix multiplication.
 -- @tparam vec3 a Left hand operand
 -- @tparam vec3 b Right hand operand
 -- @treturn vec3 out
@@ -117,6 +120,7 @@ function vec3.mul(a, b)
 end
 
 --- Divide a vector by a scalar.
+-- Component-size inv multiplication. Like a non-uniform scale().
 -- @tparam vec3 a Left hand operand
 -- @tparam vec3 b Right hand operand
 -- @treturn vec3 out
@@ -147,6 +151,9 @@ function vec3.trim(a, len)
 end
 
 --- Get the cross product of two vectors.
+-- Resulting direction is right-hand rule normal of plane defined by a and b.
+-- Magnitude is the area spanned by the parallelograms that a and b span.
+-- Order: Direction determined by right-hand rule.
 -- @tparam vec3 a Left hand operand
 -- @tparam vec3 b Right hand operand
 -- @treturn vec3 out