add docs to vector3

data/scripts/types/vector3.lua

@@ -1,3 +1,7 @@
+--- @class Vector3
+--- @field x number
+--- @field y number
+--- @field z number
 local Vector3 = {
   x = 0,
   y = 0,
@@ -8,6 +12,9 @@ local Vector3 = {
 
 setmetatable(Vector3, Vector3)
 
+---Returns true if the provided table can be coerced into a Vector3.
+---@param t table
+---@return boolean
 local function is_weak_vector3(t)
   if type(t) ~= "table" then return false end
 
@@ -19,6 +26,9 @@ local function is_weak_vector3(t)
   end
 end
 
+---Returns a Vector3 multiplied either component-wise (if b is a weak table) or multiplies each component by b if b is a number.
+---@param b number|table|Vector3
+---@return Vector3
 function Vector3:__mul(b)
   if type(b) == "number" then
     return Vector3{
@@ -39,6 +49,9 @@ function Vector3:__mul(b)
   return Vector3()
 end
 
+---Returns a Vector3 divided either component-wise (if b is a weak table) or divides each component by b if b is a number.
+---@param b number|table|Vector3
+---@return Vector3
 function Vector3:__div(b)
   if type(b) == "number" then
     return Vector3{
@@ -59,6 +72,9 @@ function Vector3:__div(b)
   return Vector3()
 end
 
+---Returns a Vector3 with each component added together.
+---@param b table|Vector3
+---@return Vector3
 function Vector3:__add(b)
   if not is_weak_vector3(b) then
     error("Vector3: other must be a Vector3-like table.")
@@ -72,6 +88,9 @@ function Vector3:__add(b)
   }
 end
 
+---Returns a Vector3 with this vector's components subtracted from b.
+---@param b table|Vector3
+---@return Vector3
 function Vector3:__sub(b)
   if not is_weak_vector3(b) then
     error("Vector3: other must be a Vector3-like table.")
@@ -85,6 +104,8 @@ function Vector3:__sub(b)
   }
 end
 
+---Returns a new Vector3 with each component being a negation of this.
+---@return Vector3
 function Vector3:__unm()
   return Vector3{
     -self.x,
@@ -141,6 +162,9 @@ function Vector3:normalized()
   return Vector3(self.x / length, self.y / length, self.z / length)
 end
 
+---Returns the dot product of this vector with `with`.
+---@param with table|Vector3
+---@return number
 function Vector3:dot(with)
   if not is_weak_vector3(with) then
     error("Vector3: with must be a Vector3-like table. Returning 0")
@@ -151,6 +175,9 @@ function Vector3:dot(with)
   return self.x * v2.x + self.y * v2.y + self.z * v2.z
 end
 
+---Returns the cross product of this vector with `with`.
+---@param with table|Vector3
+---@return Vector3
 function Vector3:cross(with)
   if not is_weak_vector3(with) then
     error("Vector3: with must be a Vector3-like table. Returning Vector3()")
@@ -164,7 +191,10 @@ function Vector3:cross(with)
   }
 end
 
-
+---Returns a vector rotated about `axis` by `angle` radians
+---@param axis table|Vector3
+---@param angle number
+---@return Vector3
 function Vector3:rotated(axis, angle)
   if not is_weak_vector3(axis) then
     error("Vector3: axis must be a Vector3-like table. Returning Vector3()")
@@ -177,7 +207,7 @@ function Vector3:rotated(axis, angle)
   -- __mul is only defined for the left operand (table), numbers don't get metatables.
   -- as such, the ordering of operations here is specific
   local v = (self * cosa) + (axis * ((1 - cosa) * self:dot(axis))) + (axis:cross(self) * sina)
-  return v
+  return Vector3(v)
 end
 
 ---- CONSTANTS