From 52eb8af61d18b5f64cf07223f36882342bfbbd05 Mon Sep 17 00:00:00 2001
From: karai17 <lmanning17@gmail.com>
Date: Sun, 24 Jul 2016 20:57:59 -0300
Subject: [PATCH] More LDoc tidying

---
 modules/quat.lua | 222 +++++++++++++++++++++++++----------------------
 modules/vec2.lua |  45 +++++-----
 modules/vec3.lua |  44 +++++-----
 3 files changed, 164 insertions(+), 147 deletions(-)

diff --git a/modules/quat.lua b/modules/quat.lua
index 2c497b8..dfadd0f 100644
--- a/modules/quat.lua
+++ b/modules/quat.lua
@@ -15,7 +15,6 @@ local sin           = math.sin
 local min           = math.min
 local max           = math.max
 local sqrt          = math.sqrt
-local pi            = math.pi
 local quat          = {}
 local quat_mt       = {}
 
@@ -41,11 +40,12 @@ end
 
 --- The public constructor.
 -- @param x Can be of two types: </br>
--- number x component
--- table {x, y, z, w} or {x = x, y = y, z = z, w = w}
--- @tparam number y y component
--- @tparam number z z component
--- @tparam number w w component
+-- number x X component
+-- table {x, y, z, w} or {x=x, y=y, z=z, w=w}
+-- @tparam number y Y component
+-- @tparam number z Z component
+-- @tparam number w W component
+-- @treturn quat out
 function quat.new(x, y, z, w)
 	-- number, number, number, number
 	if x and y and z and w then
@@ -56,7 +56,7 @@ function quat.new(x, y, z, w)
 
 		return new(x, y, z, w)
 
-	-- {x=x, y=y, z=z, w=w} or {x, y, z, w}
+	-- {x, y, z, w} or {x=x, y=y, z=z, w=w}
 	elseif type(x) == "table" then
 		local x, y, z, w = x.x or x[1], x.y or x[2], x.z or x[3], x.w or x[4]
 		assert(type(x) == "number", "new: Wrong argument type for x (<number> expected)")
@@ -70,10 +70,10 @@ function quat.new(x, y, z, w)
 	return new(0, 0, 0, 1)
 end
 
---- Create a quaternion from an axis, angle pair.
--- @tparam number angle
+--- Create a quaternion from an angle/axis pair.
+-- @tparam number angle Angle (in radians)
 -- @tparam vec3 axis
--- @treturn quat
+-- @treturn quat out
 function quat.from_angle_axis(angle, axis)
 	local len = axis:len()
 	local s   = sin(angle * 0.5)
@@ -81,10 +81,10 @@ function quat.from_angle_axis(angle, axis)
 	return new(axis.x * s, axis.y * s, axis.z * s, c)
 end
 
---- Create a quaternion from a normalized, up vector pair.
+--- Create a quaternion from a normal/up vector pair.
 -- @tparam vec3 normal
 -- @tparam vec3 up
--- @treturn quat
+-- @treturn quat out
 function quat.from_direction(normal, up)
 	local a = vec3():cross(up, normal)
 	local d = up:dot(normal)
@@ -92,16 +92,16 @@ function quat.from_direction(normal, up)
 end
 
 --- Clone a quaternion.
--- @tparam quat a
--- @treturn quat clone
+-- @tparam quat a Quaternion to clone
+-- @treturn quat out
 function quat.clone(a)
 	return new(a.x, a.y, a.z, a.w)
 end
 
---- Component-wise add a quaternion.
--- @tparam quat out
--- @tparam quat a
--- @tparam quat b
+--- Add two quaternions.
+-- @tparam quat out Quaternion to store the result
+-- @tparam quat a Left hand operant
+-- @tparam quat b Right hand operant
 -- @treturn quat out
 function quat.add(out, a, b)
 	out.x = a.x + b.x
@@ -111,10 +111,10 @@ function quat.add(out, a, b)
 	return out
 end
 
---- Component-wise subtract a quaternion.
--- @tparam quat out
--- @tparam quat a
--- @tparam quat b
+--- Subtract a quaternion from another.
+-- @tparam quat out Quaternion to store the result
+-- @tparam quat a Left hand operant
+-- @tparam quat b Right hand operant
 -- @treturn quat out
 function quat.sub(out, a, b)
 	out.x = a.x - b.x
@@ -124,10 +124,10 @@ function quat.sub(out, a, b)
 	return out
 end
 
---- Perform a quaternion multiplication.
--- @tparam quat out
--- @tparam quat a
--- @tparam quat b
+--- Multiply two quaternions.
+-- @tparam quat out Quaternion to store the result
+-- @tparam quat a Left hand operant
+-- @tparam quat b Right hand operant
 -- @treturn quat out
 function quat.mul(out, a, b)
 	out.x = a.x * b.w + a.w * b.x + a.y * b.z - a.z * b.y
@@ -137,11 +137,11 @@ function quat.mul(out, a, b)
 	return out
 end
 
---- Perform a quaternion and vec3 multiplication.
--- @tparam quat out
--- @tparam quat a
--- @tparam vec3 b
--- @treturn vec3 out
+--- Multiply a quaternion and a vec3.
+-- @tparam quat out Quaternion to store the result
+-- @tparam quat a Left hand operant
+-- @tparam vec3 b Right hand operant
+-- @treturn quat out
 local uv, uuv = vec3(), vec3()
 function quat.mul_vec3(out, a, b)
 	uv:cross(a, b)
@@ -154,10 +154,10 @@ function quat.mul_vec3(out, a, b)
 		:add(b,   out)
 end
 
---- Pow a quaternion by an exponent
--- @tparam quat out
--- @tparam quat a
--- @tparam number n
+--- Multiply a quaternion by an exponent.
+-- @tparam quat out Quaternion to store the result
+-- @tparam quat a Left hand operant
+-- @tparam number n Right hand operant
 -- @treturn quat out
 function quat.pow(out, a, n)
 	if n == 0 then
@@ -183,39 +183,39 @@ function quat.pow(out, a, n)
 end
 
 --- Normalize a quaternion.
--- @tparam quat out
--- @tparam quat a
+-- @tparam quat out Quaternion to store the result
+-- @tparam quat a Quaternion to normalize
 -- @treturn quat out
 function quat.normalize(out, a)
 	return out:scale(a, 1 / a:len())
 end
 
---- Return the inner angle between two quaternions.
--- @tparam quat a
--- @tparam quat b
--- @treturn number angle
+--- Get the dot product of two quaternions.
+-- @tparam quat a Left hand operant
+-- @tparam quat b Right hand operant
+-- @treturn number dot
 function quat.dot(a, b)
 	return a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w
 end
 
 --- Return the length of a quaternion.
--- @tparam quat a
+-- @tparam quat a Quaternion to get length of
 -- @treturn number len
 function quat.len(a)
 	return sqrt(a.x * a.x + a.y * a.y + a.z * a.z + a.w * a.w)
 end
 
 --- Return the squared length of a quaternion.
--- @tparam quat a
+-- @tparam quat a Quaternion to get length of
 -- @treturn number len
 function quat.len2(a)
 	return a.x * a.x + a.y * a.y + a.z * a.z + a.w * a.w
 end
 
---- Component-wise scale a quaternion by a scalar.
--- @tparam quat out
--- @tparam quat a
--- @tparam number s
+--- Multiply a quaternion by a scalar.
+-- @tparam quat out Quaternion to store the result
+-- @tparam quat a Left hand operant
+-- @tparam number s Right hand operant
 -- @treturn quat out
 function quat.scale(out, a, s)
 	out.x = a.x * s
@@ -226,8 +226,8 @@ function quat.scale(out, a, s)
 end
 
 --- Return the conjugate of a quaternion.
--- @tparam quat out
--- @tparam quat a
+-- @tparam quat out Quaternion to store the result
+-- @tparam quat a Quaternion to conjugate
 -- @treturn quat out
 function quat.conjugate(out, a)
 	out.x = -a.x
@@ -238,8 +238,8 @@ function quat.conjugate(out, a)
 end
 
 --- Return the inverse of a quaternion.
--- @tparam quat out
--- @tparam quat a
+-- @tparam quat out Quaternion to store the result
+-- @tparam quat a Quaternion to invert
 -- @treturn quat out
 function quat.inverse(out, a)
 	return out
@@ -248,8 +248,8 @@ function quat.inverse(out, a)
 end
 
 --- Return the reciprocal of a quaternion.
--- @tparam quat out
--- @tparam quat a
+-- @tparam quat out Quaternion to store the result
+-- @tparam quat a Quaternion to reciprocate
 -- @treturn quat out
 function quat.reciprocal(out, a)
 	assert(not a:is_zero(), "Cannot reciprocate a zero quaternion")
@@ -258,11 +258,11 @@ function quat.reciprocal(out, a)
 		:scale(out, 1 / a:len2())
 end
 
---- Linearly interpolate from one quaternion to the next.
--- @tparam quat out
--- @tparam quat a
--- @tparam quat b
--- @tparam number s 0-1 range number; 0 = a 1 = b
+--- Lerp between two quaternions.
+-- @tparam quat out Quaternion to store the result
+-- @tparam quat a Left hand operant
+-- @tparam quat b Right hand operant
+-- @tparam number s Step value
 -- @treturn quat out
 function quat.lerp(out, a, b, s)
 	return out
@@ -272,11 +272,11 @@ function quat.lerp(out, a, b, s)
 		:normalize(out)
 end
 
---- Slerp from one quaternion to the next.
--- @tparam quat out
--- @tparam quat a
--- @tparam quat b
--- @tparam number s 0-1 range number; 0 = a 1 = b
+--- Slerp between two quaternions.
+-- @tparam quat out Quaternion to store the result
+-- @tparam quat a Left hand operant
+-- @tparam quat b Right hand operant
+-- @tparam number s Step value
 -- @treturn quat out
 function quat.slerp(out, a, b, s)
 	local dot = a:dot(b)
@@ -303,8 +303,8 @@ function quat.slerp(out, a, b, s)
 		:add(tmp, out)
 end
 
---- Unpack a quaternion into form x,y,z,w.
--- @tparam quat a
+--- Unpack a quaternion into individual components.
+-- @tparam quat a Quaternion to unpack
 -- @treturn number x
 -- @treturn number y
 -- @treturn number z
@@ -313,6 +313,54 @@ function quat.unpack(a)
 	return a.x, a.y, a.z, a.w
 end
 
+--- Return a boolean showing if a table is or is not a quat.
+-- @tparam quat a Quaternion to be tested
+-- @treturn boolean is_quat
+function quat.is_quat(a)
+	if type(a) == "cdata" then
+		return ffi.istype("cpml_quat", a)
+	end
+
+	return
+		type(a)   == "table"  and
+		type(a.x) == "number" and
+		type(a.y) == "number" and
+		type(a.z) == "number" and
+		type(a.w) == "number"
+end
+
+--- Return a boolean showing if a table is or is not a zero quat.
+-- @tparam quat a Quaternion to be tested
+-- @treturn boolean is_zero
+function quat.is_zero(a)
+	return
+		a.x == 0 and
+		a.y == 0 and
+		a.z == 0 and
+		a.w == 0
+end
+
+--- Return a boolean showing if a table is or is not a real quat.
+-- @tparam quat a Quaternion to be tested
+-- @treturn boolean is_real
+function quat.is_real(a)
+	return
+		a.x == 0 and
+		a.y == 0 and
+		a.z == 0
+end
+
+--- Return a boolean showing if a table is or is not an imaginary quat.
+-- @tparam quat a Quaternion to be tested
+-- @treturn boolean is_imaginary
+function quat.is_imaginary(a)
+	return a.w == 0
+end
+
+--- Convert a quaternion into an angle/axis pair.
+-- @tparam quat a Quaternion to convert
+-- @treturn number angle
+-- @treturn vec3 axis
 function quat.to_angle_axis(a)
 	if a.w > 1 or a.w < -1 then
 		a:normalize(a)
@@ -335,6 +383,9 @@ function quat.to_angle_axis(a)
 	return angle, vec3(x, y, z)
 end
 
+--- Convert a quaternion into a vec3.
+-- @tparam quat a Quaternion to convert
+-- @treturn vec3 out
 function quat.to_vec3(a)
 	local out = vec3()
 	out.x = a.x
@@ -343,48 +394,13 @@ function quat.to_vec3(a)
 	return out
 end
 
---- Return a string formatted "{x, y, z, w}"
--- @tparam quat a
--- @treturn string
+--- Return a formatted string.
+-- @tparam quat a Quaternion to be turned into a string
+-- @treturn string formatted
 function quat.to_string(a)
 	return string.format("(%+0.3f,%+0.3f,%+0.3f,%+0.3f)", a.x, a.y, a.z, a.w)
 end
 
---- Return a boolean showing if a table is or is not a quat
--- @param q object to be tested
--- @treturn boolean
-function quat.is_quat(a)
-	if type(a) == "cdata" then
-		return ffi.istype("cpml_quat", a)
-	end
-
-	return
-		type(a)   == "table"  and
-		type(a.x) == "number" and
-		type(a.y) == "number" and
-		type(a.z) == "number" and
-		type(a.w) == "number"
-end
-
-function quat.is_zero(a)
-	return
-		a.x == 0 and
-		a.y == 0 and
-		a.z == 0 and
-		a.w == 0
-end
-
-function quat.is_real(a)
-	return
-		a.x == 0 and
-		a.y == 0 and
-		a.z == 0
-end
-
-function quat.is_imaginary(a)
-	return a.w == 0
-end
-
 quat_mt.__index    = quat
 quat_mt.__tostring = quat.to_string
 
diff --git a/modules/vec2.lua b/modules/vec2.lua
index 31b10f1..0e423af 100644
--- a/modules/vec2.lua
+++ b/modules/vec2.lua
@@ -40,6 +40,7 @@ vec2.zero   = new(0, 0)
 -- table {x, y} or {x = x, y = y}
 -- scalar to fill the vector eg. {x, x}
 -- @tparam number y Y component
+-- @treturn vec2 out
 function vec2.new(x, y)
 	-- number, number
 	if x and y then
@@ -67,14 +68,14 @@ end
 --- Convert point from polar to cartesian.
 -- @tparam number radius Radius of the point
 -- @tparam number theta Angle of the point (in radians)
--- @treturn vec2
+-- @treturn vec2 out
 function vec2.from_cartesian(radius, theta)
 	return new(radius * cos(theta), radius * sin(theta))
 end
 
 --- Clone a vector.
 -- @tparam vec2 a Vector to be cloned
--- @treturn vec2
+-- @treturn vec2 out
 function vec2.clone(a)
 	return new(a.x, a.y)
 end
@@ -83,7 +84,7 @@ end
 -- @tparam vec2 out Vector to store the result
 -- @tparam vec2 a Left hand operant
 -- @tparam vec2 b Right hand operant
--- @treturn vec2
+-- @treturn vec2 out
 function vec2.add(out, a, b)
 	out.x = a.x + b.x
 	out.y = a.y + b.y
@@ -94,7 +95,7 @@ end
 -- @tparam vec2 out Vector to store the result
 -- @tparam vec2 a Left hand operant
 -- @tparam vec2 b Right hand operant
--- @treturn vec2
+-- @treturn vec2 out
 function vec2.sub(out, a, b)
 	out.x = a.x - b.x
 	out.y = a.y - b.y
@@ -105,7 +106,7 @@ end
 -- @tparam vec2 out Vector to store the result
 -- @tparam vec2 a Left hand operant
 -- @tparam vec2 b Right hand operant
--- @treturn vec2
+-- @treturn vec2 out
 function vec2.mul(out, a, b)
 	out.x = a.x * b
 	out.y = a.y * b
@@ -116,7 +117,7 @@ end
 -- @tparam vec2 out Vector to store the result
 -- @tparam vec2 a Left hand operant
 -- @tparam vec2 b Right hand operant
--- @treturn vec2
+-- @treturn vec2 out
 function vec2.div(out, a, b)
 	out.x = a.x / b
 	out.y = a.y / b
@@ -126,7 +127,7 @@ end
 --- Get the normal of a vector.
 -- @tparam vec2 out Vector to store the result
 -- @tparam vec2 a Vector to normalize
--- @treturn vec2
+-- @treturn vec2 out
 function vec2.normalize(out, a)
 	local l = a:len()
 	out.x = a.x / l
@@ -138,7 +139,7 @@ end
 -- @tparam vec2 out Vector to store the result
 -- @tparam vec2 a Vector to be trimmed
 -- @tparam number len Length to trim the vector to
--- @treturn vec2
+-- @treturn vec2 out
 function vec2.trim(out, a, len)
 	return out
 		:normalize(a)
@@ -148,7 +149,7 @@ end
 --- Get the cross product of two vectors.
 -- @tparam vec2 a Left hand operant
 -- @tparam vec2 b Right hand operant
--- @treturn number Magnitude of cross product in 3D
+-- @treturn number magnitude
 function vec2.cross(a, b)
 	return a.x * b.y - a.y * b.x
 end
@@ -156,21 +157,21 @@ end
 --- Get the dot product of two vectors.
 -- @tparam vec2 a Left hand operant
 -- @tparam vec2 b Right hand operant
--- @treturn number
+-- @treturn number dot
 function vec2.dot(a, b)
 	return a.x * b.x + a.y * b.y
 end
 
 --- Get the length of a vector.
 -- @tparam vec2 a Vector to get the length of
--- @treturn number
+-- @treturn number len
 function vec2.len(a)
 	return sqrt(a.x * a.x + a.y * a.y)
 end
 
 --- Get the squared length of a vector.
 -- @tparam vec2 a Vector to get the squared length of
--- @treturn number
+-- @treturn number len
 function vec2.len2(a)
 	return a.x * a.x + a.y * a.y
 end
@@ -178,7 +179,7 @@ end
 --- Get the distance between two vectors.
 -- @tparam vec2 a Left hand operant
 -- @tparam vec2 b Right hand operant
--- @treturn number
+-- @treturn number dist
 function vec2.dist(a, b)
 	local dx = a.x - b.x
 	local dy = a.y - b.y
@@ -188,7 +189,7 @@ end
 --- Get the squared distance between two vectors.
 -- @tparam vec2 a Left hand operant
 -- @tparam vec2 b Right hand operant
--- @treturn number
+-- @treturn number dist
 function vec2.dist2(a, b)
 	local dx = a.x - b.x
 	local dy = a.y - b.y
@@ -199,7 +200,7 @@ end
 -- @tparam vec2 out Vector to store the result
 -- @tparam vec2 a Vector to rotate
 -- @tparam number phi Angle to rotate vector by (in radians)
--- @treturn vec2
+-- @treturn vec2 out
 function vec2.rotate(out, a, phi)
 	local c = cos(phi)
 	local s = sin(phi)
@@ -211,7 +212,7 @@ end
 --- Get the perpendicular vector of a vector.
 -- @tparam vec2 out Vector to store the result
 -- @tparam vec2 a Vector to get perpendicular axes from
--- @treturn vec2
+-- @treturn vec2 out
 function vec2.perpendicular(out, a)
 	out.x = -a.y
 	out.y =  a.x
@@ -223,7 +224,7 @@ end
 -- @tparam vec2 a Left hand operant
 -- @tparam vec2 b Right hand operant
 -- @tparam number s Step value
--- @treturn vec2
+-- @treturn vec2 out
 function vec2.lerp(out, a, b, s)
 	return out
 		:sub(b, a)
@@ -233,15 +234,15 @@ end
 
 --- Unpack a vector into individual components.
 -- @tparam vec2 a Vector to unpack
--- @treturn number x X component
--- @treturn number y Y component
+-- @treturn number x
+-- @treturn number y
 function vec2.unpack(a)
 	return a.x, a.y
 end
 
 --- Return a boolean showing if a table is or is not a vec2.
 -- @tparam vec2 a Vector to be tested
--- @treturn boolean
+-- @treturn boolean is_vec2
 function vec2.is_vec2(a)
 	if type(a) == "cdata" then
 		return ffi.istype("cpml_vec2", a)
@@ -255,7 +256,7 @@ end
 
 --- Return a boolean showing if a table is or is not a zero vec2.
 -- @tparam vec2 a Vector to be tested
--- @treturn boolean
+-- @treturn boolean is_zero
 function vec2.is_zero(a)
 	return a.x == 0 and a.y == 0
 end
@@ -273,7 +274,7 @@ end
 
 --- Return a formatted string.
 -- @tparam vec2 a Vector to be turned into a string
--- @treturn string
+-- @treturn string formatted
 function vec2.to_string(a)
 	return string.format("(%+0.3f,%+0.3f)", a.x, a.y)
 end
diff --git a/modules/vec3.lua b/modules/vec3.lua
index 34a0d2f..ac43782 100644
--- a/modules/vec3.lua
+++ b/modules/vec3.lua
@@ -45,7 +45,7 @@ local tmp = new(0, 0, 0)
 -- scalar To fill the vector eg. {x, x, x}
 -- @tparam number y Y component
 -- @tparam number z Z component
--- @treturn vec3
+-- @treturn vec3 out
 function vec3.new(x, y, z)
 	-- number, number, number
 	if x and y and z then
@@ -74,7 +74,7 @@ end
 
 --- Clone a vector.
 -- @tparam vec3 a Vector to be cloned
--- @treturn vec3
+-- @treturn vec3 out
 function vec3.clone(a)
 	return new(a.x, a.y, a.z)
 end
@@ -83,7 +83,7 @@ end
 -- @tparam vec3 out Vector to store the result
 -- @tparam vec3 a Left hand operant
 -- @tparam vec3 b Right hand operant
--- @treturn vec3
+-- @treturn vec3 out
 function vec3.add(out, a, b)
 	out.x = a.x + b.x
 	out.y = a.y + b.y
@@ -95,7 +95,7 @@ end
 -- @tparam vec3 out Vector to store the result
 -- @tparam vec3 a Left hand operant
 -- @tparam vec3 b Right hand operant
--- @treturn vec3
+-- @treturn vec3 out
 function vec3.sub(out, a, b)
 	out.x = a.x - b.x
 	out.y = a.y - b.y
@@ -107,7 +107,7 @@ end
 -- @tparam vec3 out Vector to store the result
 -- @tparam vec3 a Left hand operant
 -- @tparam number b Right hand operant
--- @treturn vec3
+-- @treturn vec3 out
 function vec3.mul(out, a, b)
 	out.x = a.x * b
 	out.y = a.y * b
@@ -119,7 +119,7 @@ end
 -- @tparam vec3 out Vector to store the result
 -- @tparam vec3 a Left hand operant
 -- @tparam number b Right hand operant
--- @treturn vec3
+-- @treturn vec3 out
 function vec3.div(out, a, b)
 	out.x = a.x / b
 	out.y = a.y / b
@@ -130,7 +130,7 @@ end
 --- Get the normal of a vector.
 -- @tparam vec3 out Vector to store the result
 -- @tparam vec3 a Vector to normalize
--- @treturn vec3
+-- @treturn vec3 out
 function vec3.normalize(out, a)
 	local l = vec3.len(a)
 	out.x = a.x / l
@@ -143,7 +143,7 @@ end
 -- @tparam vec3 out Vector to store the result
 -- @tparam vec3 a Vector to be trimmed
 -- @tparam number len Length to trim the vector to
--- @treturn vec3
+-- @treturn vec3 out
 function vec3.trim(out, a, len)
 	return out
 		:normalize(a)
@@ -154,7 +154,7 @@ end
 -- @tparam vec3 out Vector to store the result
 -- @tparam vec3 a Left hand operant
 -- @tparam vec3 b Right hand operant
--- @treturn vec3
+-- @treturn vec3 out
 function vec3.cross(out, a, b)
 	out.x = a.y * b.z - a.z * b.y
 	out.y = a.z * b.x - a.x * b.z
@@ -165,21 +165,21 @@ end
 --- Get the dot product of two vectors.
 -- @tparam vec3 a Left hand operant
 -- @tparam vec3 b Right hand operant
--- @treturn number
+-- @treturn number dot
 function vec3.dot(a, b)
 	return a.x * b.x + a.y * b.y + a.z * b.z
 end
 
 --- Get the length of a vector.
 -- @tparam vec3 a Vector to get the length of
--- @treturn number
+-- @treturn number len
 function vec3.len(a)
 	return sqrt(a.x * a.x + a.y * a.y + a.z * a.z)
 end
 
 --- Get the squared length of a vector.
 -- @tparam vec3 a Vector to get the squared length of
--- @treturn number
+-- @treturn number len
 function vec3.len2(a)
 	return a.x * a.x + a.y * a.y + a.z * a.z
 end
@@ -187,7 +187,7 @@ end
 --- Get the distance between two vectors.
 -- @tparam vec3 a Left hand operant
 -- @tparam vec3 b Right hand operant
--- @treturn number
+-- @treturn number dist
 function vec3.dist(a, b)
 	local dx = a.x - b.x
 	local dy = a.y - b.y
@@ -198,7 +198,7 @@ end
 --- Get the squared distance between two vectors.
 -- @tparam vec3 a Left hand operant
 -- @tparam vec3 b Right hand operant
--- @treturn number
+-- @treturn number dist
 function vec3.dist2(a, b)
 	local dx = a.x - b.x
 	local dy = a.y - b.y
@@ -211,7 +211,7 @@ end
 -- @tparam vec3 a Vector to rotate
 -- @tparam number phi Amount to rotate, in radians
 -- @tparam vec3 axis Axis to rotate by
--- @treturn vec3
+-- @treturn vec3 out
 function vec3.rotate(out, a, phi, axis)
 	if not vec3.is_vec3(axis) then
 		return a
@@ -244,7 +244,7 @@ end
 -- @tparam vec3 a Left hand operant
 -- @tparam vec3 b Right hand operant
 -- @tparam number s Step value
--- @treturn vec3
+-- @treturn vec3 out
 function vec3.lerp(out, a, b, s)
 	return out
 		:sub(b, a)
@@ -254,16 +254,16 @@ end
 
 --- Unpack a vector into individual components.
 -- @tparam vec3 a Vector to unpack
--- @treturn number x x component
--- @treturn number y y component
--- @treturn number z z component
+-- @treturn number x
+-- @treturn number y
+-- @treturn number z
 function vec3.unpack(a)
 	return a.x, a.y, a.z
 end
 
 --- Return a boolean showing if a table is or is not a vec3.
 -- @tparam vec3 a Vector to be tested
--- @treturn boolean
+-- @treturn boolean is_vec3
 function vec3.is_vec3(a)
 	if type(a) == "cdata" then
 		return ffi.istype("cpml_vec3", a)
@@ -278,7 +278,7 @@ end
 
 --- Return a boolean showing if a table is or is not a zero vec3.
 -- @tparam vec3 a Vector to be tested
--- @treturn boolean
+-- @treturn boolean is_zero
 function vec3.is_zero(a)
 	return
 		a.x == 0 and
@@ -288,7 +288,7 @@ end
 
 --- Return a formatted string.
 -- @tparam vec3 a Vector to be turned into a string
--- @treturn string
+-- @treturn string formatted
 function vec3.to_string(a)
 	return string.format("(%+0.3f,%+0.3f,%+0.3f)", a.x, a.y, a.z)
 end