adds docs && some vec functions

res/modules/vectors.lua

@@ -17,6 +17,7 @@ function vector2:new(x, y)
         x = x or 0,
         y = y or 0
     }
+
     setmetatable(obj, self)
     return obj
 end
@@ -27,6 +28,15 @@ function vector2:strvec2()
 end
 
 -- round vector components
+-- @param decimals -> integer
+-- @return round(vec2)
+-- @usage:
+--      @example-1:
+--              local v1 = vec2(1, 0.5)
+--              print(v1:round()) -- Output: (1, 1)
+--      @example-2:
+--              local v1 = vec2(0.707, 0.5)
+--              print(v1:round(2)) -- Output: (0.71, 0.5)
 function vector2:round(decimals)
     decimals = decimals or 0
     self.x = math.floor(self.x * 10^decimals + 0.5) / 10^decimals
@@ -34,26 +44,59 @@ function vector2:round(decimals)
     return self
 end
 
--- magnitude (length) vec
-function vector2:len()
+
+-- vec2 magnitude (length)
+-- @return {number} - the magnitude of the vector
+-- @usage:
+--      @example-1:
+--              local v1 = vec2(-10, 25)
+--              print(v1:len()) -- Output: 26.925824035673
+--      @example-2:
+--              local v1 = vec2(0.32, 89)
+--              print(v1:len()) -- Output: 89.
+function vector2:len() 
     return math.sqrt(self.x * self.x + self.y * self.y)
 end
 
--- normalize vector
+
+-- Normalize vec2
+-- @return {vector2} - The normalized vector2
+-- @usage:
+--      @example-1:
+--              local v1 = vec2(10, 15)
+--              print(v1:norm()) -- Output: (0.55470019622523, 0.83205029433784)
+--      @example-2:
+--              local v1 = vec2(-1, 1)
+--              print(v1:norm()) -- Output: (-0.70710678118655, 0.70710678118655)
 function vector2:norm()
     local length_vectors = self:len()
     return vector2:new(self.x / length_vectors, self.y / length_vectors)
 end
 
--- dot product
-function vector2:dot(v)
-    if type(v) == "number" then
+
+-- vec2 dot product
+-- @param vector {vec2} 
+-- @return {number}
+-- @usage:
+--      @example-1:
+--              local v1 = vec2(10, 15)
+--              local v2 = vec2(-1, 1)
+--              print(v1:dot(v2)) -- Output: 5
+--      @example-2:
+--              local v1 = vec2(-15, 10)
+--              print(v1:dot(v1)) -- Output: (-0.83205029433784, 0.55470019622523)
+function vector2:dot(vector)
+    if type(vector) == "number" then
         error("Invalid input argument. Expected a vector2 object")
     end
-    return self.x * v.x + self.y * v.y
+    return self.x * vector.x + self.y * vector.y
 end
 
--- linear interpolation 
+
+-- Linear interpolation for vector2
+-- @param b {vector2} - The target vector2
+-- @param t {number} - (0 <= t <= 1) the interpolation factor
+-- @return {vector2} - The interpolated vector2
 function vector2:lerp(b, t)
     if type(b) ~= "vector2" then
         error("Invalid input argument. Expected a vector2 object")
@@ -64,11 +107,11 @@ function vector2:lerp(b, t)
     return vector2:new(self.x + t * (b.x - self.x), self.y + t * (b.y - self.y));
 end
 
--- rot vec2
--- @param angle -> float (radians)
--- @param axis -> string || nil .. if nil => rot axis z
--- @param convert2deg -> bool .. if true => deg2rad
--- @return vec2
+-- rotate vec2
+-- @param angle {number}
+-- @param axis {string} - axis rotate around (x, y, or z)
+-- @param convert2deg {bool} .. if true => deg convert to rad 
+-- @return {vector2} - rotated vector2
 function vector2:rot(angle, axis, convert2deg)
     if convert2deg == true then 
         angle = math.rad(angle) 
@@ -177,9 +220,6 @@ function vector2.__tostring(vcrt)
 end
 
 
-
-
-
 -- vec3 construct
 function vector3:new(x, y, z)
     if type(x) ~= "number" or type(y) ~= "number" or type(z) ~= "number" then
@@ -200,7 +240,13 @@ function vector3:strvec3()
     return "(" .. self.x .. ", " .. self.y .. ", " .. self.z .. ")"
 end
   
-  -- dot product
+-- dot product
+-- @param {vec3}
+-- @return {number} -> float || integer
+-- @usage:
+--     local v1 = vec3(10, 15)
+--     local v2 = vec3(15, 10, 1)
+--     print(v1:dot(v2)) -- Output: 301
 function vector3:dot(v)
     if type(v) == "number" then
         print("\n(( TypeError : dot ))\nType arg dot(vector3), your arg: " .. "dot(" .. type(v) .. ")")
@@ -209,7 +255,7 @@ function vector3:dot(v)
     return self.x * v.x + self.y * v.y + self.z * v.z
 end
   
-  -- cross product
+-- cross product
 function vector3:cross(v)
     if type(v) == "number" then
         print("\n(( TypeError : cross ))\nType arg cross(vector3), your arg: " .. "cross(" .. type(v) .. ")")
@@ -222,7 +268,7 @@ function vector3:cross(v)
     )
 end
   
-  -- round vector components
+-- round vector components
 function vector3:round(decimals)
     decimals = decimals or 0
     self.x = math.floor(self.x * 10^decimals + 0.5) / 10^decimals
@@ -233,14 +279,22 @@ end
   
 
 -- check if two vectors are parallel
-function vector3:is_parallel(v)
-    if type(v) ~= "vector3" then
-        error("Invalid input argument. Expected a vector3 object.")
+-- @param {vec3}
+-- @return {bool}
+-- @usage:
+--      local v1 = vec3(10, 15, 1)
+--      local v2 = vec3(10, 15, 1)
+--      print(v1:isParallel(v2)) -- Output: true
+function vector3:isParallel(val)
+    if type(val) ~= "table" or type(val) == "number" then
+        print("\n(( TypeError : isParallel ))\nType arg isParallel(vector3)")
+        error("Invalid input argument. Expected a vector3 object.\n")
     end
-    return self:cross(v):len() < 1e-6
+    return self:cross(val):len() < 1e-6
 end
 
 -- magnitude (length) vec
+-- @return {number}
 function vector3:len()
     return math.sqrt(self.x * self.x + self.y * self.y + self.z * self.z)
 end
@@ -248,6 +302,10 @@ end
 
 
 -- normalize vector
+-- @return {number}
+-- @usage:
+--      local v1 = vec3(10, 15, 1)
+--      print(v1:norm()) -- Output: 18.1
 function vector3:norm()
     local length_vectors = self:len()
     return vector3:new(self.x / length_vectors, self.y / length_vectors, self.z / length_vectors)
@@ -255,6 +313,9 @@ end
 
 
 -- linear interpolation (lerp) for vector3
+-- @param b {vec3} - The target vector3 object
+-- @param t {number} - (0 <= t <= 1) the interpolation factor
+-- @return {vec3}
 function vector3:lerp(b, t)
     if type(b) ~= "vector3" then
         error("Invalid input argument. Expected a vector3 object")
@@ -267,15 +328,15 @@ end
 
 
 -- rot vec3
--- @param angle -> float
--- @param axis -> string || nil .. if nil => rot axis z
--- @param convert2deg -> bool || nil .. if true => deg2rad
--- @return vec3
+-- @param angle {number} -> float || int
+-- @param axis {string}  .. if nil => rot axis z
+-- @param convert2deg {bool} .. if true => deg convert to rad
+-- @return {vec3}
 function vector3:rot(angle, axis, convert2deg)
     if convert2deg == true then
         angle = math.rad(angle)
     end
-    
+
     if type(axis) == "string" then
         local cx, sx = math.cos(angle), math.sin(angle)
         if axis == "x" then
@@ -442,3 +503,4 @@ end
 function vector3.__tostring(vcrt3)
     return vcrt3:strvec3()
 end
+