Finish emmy lua docs

src/ItemBook/ItemBook.lua

@@ -6,6 +6,7 @@ local ItemBook = {}
 ItemBook.__index = ItemBook
 
 -- Constructor
+---@return ItemBook
 function ItemBook:New()
     local self = setmetatable({}, ItemBook)
     self.items = {}
@@ -13,6 +14,7 @@ function ItemBook:New()
 end
 
 -- Get a spell from the ItemBook
+---@param id number
 ---@return Item
 function ItemBook:GetItem(id)
     if self.items[id] == nil then

src/List/List.lua

@@ -22,32 +22,42 @@ local List = {
 }
 List.__index = List
 
+---@param from table | nil
+---@return List
 function List:New(from)
     local self = setmetatable({}, List)
     self._list = from or {}
     return self
 end
 
+---@param value any
+---@return nil
 function List:push(value)
     table.insert(self._list, value)
 end
 
+---@return any
 function List:pop()
     return table.remove(self._list)
 end
 
+---@return any
 function List:peek()
     return self._list[#self._list]
 end
 
+---@return number
 function List:count()
     return #self._list
 end
 
+---@return nil
 function List:clear()
     self._list = {}
 end
 
+---@param value any
+---@return boolean
 function List:contains(value)
     for _, v in ipairs(self._list) do
         if v == value then
@@ -57,6 +67,8 @@ function List:contains(value)
     return false
 end
 
+---@param value any
+---@return boolean
 function List:remove(value)
     for i, v in ipairs(self._list) do
         if v == value then
@@ -67,6 +79,8 @@ function List:remove(value)
     return false
 end
 
+---@param callback fun(value: any): boolean
+---@return nil
 function List:each(callback)
     for _, v in ipairs(self._list) do
         if callback(v) then
@@ -75,6 +89,8 @@ function List:each(callback)
     end
 end
 
+---@param callback fun(value: any): boolean
+---@return boolean
 function List:map(callback)
     local newList = List.new()
     for _, v in ipairs(self._list) do
@@ -83,6 +99,8 @@ function List:map(callback)
     return newList
 end
 
+---@param callback fun(value: any): boolean
+---@return boolean
 function List:filter(callback)
     local newList = List.new()
     for _, v in ipairs(self._list) do
@@ -93,6 +111,9 @@ function List:filter(callback)
     return newList
 end
 
+---@param callback fun(value: any): boolean
+---@param initialValue any
+---@return boolean
 function List:reduce(callback, initialValue)
     local result = initialValue
     for _, v in ipairs(self._list) do
@@ -101,6 +122,8 @@ function List:reduce(callback, initialValue)
     return result
 end
 
+---@param callback fun(value: any): boolean
+---@return boolean | nil
 function List:find(callback)
     for _, v in ipairs(self._list) do
         if callback(v) then
@@ -110,6 +133,8 @@ function List:find(callback)
     return nil
 end
 
+---@param callback fun(value: any): boolean
+---@return number | nil
 function List:findIndex(callback)
     for i, v in ipairs(self._list) do
         if callback(v) then
@@ -119,10 +144,13 @@ function List:findIndex(callback)
     return nil
 end
 
+---@param callback fun(value: any): boolean
+---@return nil
 function List:sort(callback)
     table.sort(self._list, callback)
 end
 
+---@return List
 function List:reverse()
     local newList = List.new()
     for i = #self._list, 1, -1 do
@@ -131,6 +159,7 @@ function List:reverse()
     return newList
 end
 
+---@return List
 function List:clone()
     local newList = List.new()
     for _, v in ipairs(self._list) do
@@ -139,6 +168,8 @@ function List:clone()
     return newList
 end
 
+---@param list List
+---@return List
 function List:concat(list)
     local newList = List.new()
     for _, v in ipairs(self._list) do
@@ -150,6 +181,8 @@ function List:concat(list)
     return newList
 end
 
+---@param separator string
+---@return string
 function List:join(separator)
     local result = ""
     for i, v in ipairs(self._list) do
@@ -161,10 +194,12 @@ function List:join(separator)
     return result
 end
 
+---@return string
 function List:toString()
     return self:join(", ")
 end
 
+---@return string
 function List:__tostring()
     return self:toString()
 end

src/Module/Module.lua

@@ -5,10 +5,14 @@ local Module = {}
 Module.__index = Module
 
 -- __tostring
+---@return string
 function Module:__tostring()
     return "Bastion.__Module(" .. self.name .. ")"
 end
 
+-- Constructor
+---@param name string
+---@return Module
 function Module:New(name)
     local module = {}
     setmetatable(module, Module)
@@ -21,16 +25,19 @@ function Module:New(name)
 end
 
 -- Enable the module
+---@return nil
 function Module:Enable()
     self.enabled = true
 end
 
 -- Disable the module
+---@return nil
 function Module:Disable()
     self.enabled = false
 end
 
 -- Toggle the module
+---@return nil
 function Module:Toggle()
     if self.enabled then
         self:Disable()
@@ -40,11 +47,15 @@ function Module:Toggle()
 end
 
 -- Add a function to the sync list
+---@param func function
+---@return nil
 function Module:Sync(func)
     table.insert(self.synced, func)
 end
 
 -- Remove a function from the sync list
+---@param func function
+---@return nil
 function Module:Unsync(func)
     for i = 1, #self.synced do
         if self.synced[i] == func then
@@ -55,6 +66,7 @@ function Module:Unsync(func)
 end
 
 -- Sync
+---@return nil
 function Module:Tick()
     if self.enabled then
         for i = 1, #self.synced do

src/MythicPlusUtils/MythicPlusUtils.lua

@@ -12,6 +12,7 @@ local MythicPlusUtils = {
 
 MythicPlusUtils.__index = MythicPlusUtils
 
+---@return MythicPlusUtils
 function MythicPlusUtils:New()
     local self = setmetatable({}, MythicPlusUtils)
 
@@ -148,14 +149,19 @@ function MythicPlusUtils:New()
     return self
 end
 
+---@return nil
 function MythicPlusUtils:ToggleDebuffLogging()
     self.debuffLogging = not self.debuffLogging
 end
 
+---@return nil
 function MythicPlusUtils:ToggleCastLogging()
     self.castLogging = not self.castLogging
 end
 
+---@param unit Unit
+---@param percent number
+---@return boolean
 function MythicPlusUtils:CastingCriticalKick(unit, percent)
     local castingSpell = unit:GetCastingOrChannelingSpell()
 

src/NotificationsList/NotificationsList.lua

@@ -7,6 +7,7 @@ local NotificationsList = {
 NotificationsList.__index = NotificationsList
 
 -- Constructor
+---@return NotificationsList
 function NotificationsList:New()
     local self = setmetatable({}, NotificationsList)
 
@@ -36,6 +37,11 @@ local Notification = {
 Notification.__index = Notification
 
 -- Constructor
+---@param list NotificationsList
+---@param icon string
+---@param text string
+---@param duration number
+---@return Notification
 function Notification:New(list, icon, text, duration)
     local self = setmetatable({}, Notification)
 
@@ -70,6 +76,7 @@ function Notification:New(list, icon, text, duration)
 end
 
 -- Remove notification
+---@return nil
 function Notification:Remove()
     -- Fade out the notification frame and remove it after the fade
     UIFrameFadeOut(self.frame, 0.2, 1, 0)
@@ -83,6 +90,10 @@ function Notification:Remove()
 end
 
 -- Add a notification to the list
+---@param icon string
+---@param text string
+---@param duration number
+---@return nil
 function NotificationsList:AddNotification(icon, text, duration)
     -- Create a new notification
     local notification = Notification:New(self, icon, text, duration)
@@ -96,6 +107,7 @@ function NotificationsList:AddNotification(icon, text, duration)
 end
 
 -- Update the notifications
+---@return nil
 function NotificationsList:Update()
     -- Loop through the notifications
     for i, notification in ipairs(self.notifications) do
@@ -105,6 +117,8 @@ function NotificationsList:Update()
 end
 
 -- Remove a notification from the list
+---@param notification Notification
+---@return nil
 function NotificationsList:RemoveNotification(notification)
     -- Loop through the notifications
     for i, v in ipairs(self.notifications) do
@@ -119,6 +133,7 @@ function NotificationsList:RemoveNotification(notification)
 end
 
 -- Remove all notifications from the list
+---@return nil
 function NotificationsList:RemoveAllNotifications()
     -- Loop through the notifications
     for i, v in ipairs(self.notifications) do

src/ObjectManager/ObjectManager.lua

@@ -18,6 +18,9 @@ function ObjectManager:New()
 end
 
 -- Register a custom list with a callback
+---@param name string
+---@param cb function
+---@return List
 function ObjectManager:RegisterList(name, cb)
     if self._lists[name] then
         return false
@@ -32,6 +35,7 @@ function ObjectManager:RegisterList(name, cb)
 end
 
 -- reset custom lists
+---@return nil
 function ObjectManager:ResetLists()
     for _, list in pairs(self._lists) do
         list.list:clear()
@@ -39,6 +43,8 @@ function ObjectManager:ResetLists()
 end
 
 -- Refresh custom lists
+---@param object table
+---@return nil
 function ObjectManager:EnumLists(object)
     for _, list in pairs(self._lists) do
         local r = list.cb(object)
@@ -49,10 +55,14 @@ function ObjectManager:EnumLists(object)
 end
 
 -- Get a list
+---@param name string
+---@return List
 function ObjectManager:GetList(name)
     return self._lists[name].list
 end
 
+-- Refresh all lists
+---@return nil
 function ObjectManager:Refresh()
     self.enemies:clear()
     self.friends:clear()

src/Refreshable/Refreshable.lua

@@ -22,11 +22,15 @@ function Refreshable:__index(k)
 end
 
 -- When the object is accessed return the value
+---@return string
 function Refreshable:__tostring()
     return "Bastion.__Refreshable(" .. tostring(rawget(self, 'value')) .. ")"
 end
 
 -- Create
+---@param value any
+---@param cb function
+---@return Refreshable
 function Refreshable:New(value, cb)
     local self = setmetatable({}, Refreshable)
 
@@ -40,6 +44,7 @@ function Refreshable:New(value, cb)
 end
 
 -- Try to update the value
+---@return nil
 function Refreshable:TryUpdate()
     if self.cache:IsCached("value") then
         self.value = self.callback()
@@ -47,16 +52,21 @@ function Refreshable:TryUpdate()
 end
 
 -- Update the value
+---@return nil
 function Refreshable:Update()
     self.value = self.callback()
 end
 
 -- Set a new value
+---@param value any
+---@return nil
 function Refreshable:Set(value)
     self.value = value
 end
 
 -- Set a new callback
+---@param cb function
+---@return nil
 function Refreshable:SetCallback(cb)
     self.callback = cb
 end

src/Spell/Spell.lua

@@ -32,16 +32,21 @@ function Spell:__index(k)
 end
 
 -- Equals
+---@param other Spell
+---@return boolean
 function Spell:__eq(other)
     return self:GetID() == other:GetID()
 end
 
 -- tostring
+---@return string
 function Spell:__tostring()
     return "Bastion.__Spell(" .. self:GetID() .. ")" .. " - " .. self:GetName()
 end
 
 -- Constructor
+---@param id number
+---@return Spell
 function Spell:New(id)
     local self = setmetatable({}, Spell)
 
@@ -51,59 +56,72 @@ function Spell:New(id)
 end
 
 -- Get the spells id
+---@return number
 function Spell:GetID()
     return self.spellID
 end
 
 -- Add post cast func
 ---@param func fun(self:Spell)
+---@return Spell
 function Spell:PostCast(func)
     self.PostCastFunc = func
     return self
 end
 
 -- Get the spells name
+---@return string
 function Spell:GetName()
     return GetSpellInfo(self:GetID())
 end
 
 -- Get the spells icon
+---@return number
 function Spell:GetIcon()
     return select(3, GetSpellInfo(self:GetID()))
 end
 
 -- Get the spells cooldown
+---@return number
 function Spell:GetCooldown()
     return select(2, GetSpellCooldown(self:GetID()))
 end
 
 -- Return the castable function
+---@return fun(self:Spell):boolean
 function Spell:GetCastableFunction()
     return self.CastableIfFunc
 end
 
 -- Return the precast function
+---@return fun(self:Spell)
 function Spell:GetPreCastFunction()
     return self.PreCastFunc
 end
 
 -- Get the on cast func
+---@return fun(self:Spell)
 function Spell:GetOnCastFunction()
     return self.OnCastFunc
 end
 
 -- Get the spells cooldown remaining
+---@return number
 function Spell:GetCooldownRemaining()
     local start, duration = GetSpellCooldown(self:GetID())
     return start + duration - GetTime()
 end
 
 -- On cooldown
+---@return boolean
 function Spell:OnCooldown()
     return self:GetCooldownRemaining() > 0
 end
 
 -- Cast the spell
+---@param unit Unit
+---@param condition string
+---@return boolean
 function Spell:Cast(unit, condition)
     if condition and not self:EvaluateCondition(condition) then
         return false
@@ -140,14 +158,18 @@ function Spell:Cast(unit, condition)
     if self:GetOnCastFunction() then
         self:GetOnCastFunction()(self)
     end
+
+    return true
 end
 
 -- Get post cast func
+---@return fun(self:Spell)
 function Spell:GetPostCastFunction()
     return self.PostCastFunc
 end
 
 -- Check if the spell is known
+---@return boolean
 function Spell:IsKnown()
     local isKnown = IsSpellKnown(self:GetID())
     local isPlayerSpell = IsPlayerSpell(self:GetID())
@@ -155,22 +177,26 @@ function Spell:IsKnown()
 end
 
 -- Check if the spell is on cooldown
+---@return boolean
 function Spell:IsOnCooldown()
     return select(2, GetSpellCooldown(self:GetID())) > 0
 end
 
 -- Check if the spell is usable
+---@return boolean
 function Spell:IsUsable()
     local usable, noMana = IsUsableSpell(self:GetID())
     return usable or usableExcludes[self:GetID()]
 end
 
 -- Check if the spell is castable
+---@return boolean
 function Spell:IsKnownAndUsable()
     return self:IsKnown() and not self:IsOnCooldown() and self:IsUsable()
 end
 
 -- Check if the spell is castable
+---@return boolean
 function Spell:Castable()
     if self:GetCastableFunction() then
         return self:GetCastableFunction()(self)
@@ -181,6 +207,7 @@ end
 
 -- Set a script to check if the spell is castable
 ---@param func fun(spell:Spell):boolean
+---@return Spell
 function Spell:CastableIf(func)
     self.CastableIfFunc = func
     return self
@@ -188,6 +215,7 @@ end
 
 -- Set a script to run before the spell has been cast
 ---@param func fun(spell:Spell)
+---@return Spell
 function Spell:PreCast(func)
     self.PreCastFunc = func
     return self
@@ -195,17 +223,23 @@ end
 
 -- Set a script to run after the spell has been cast
 ---@param func fun(spell:Spell)
+---@return Spell
 function Spell:OnCast(func)
     self.OnCastFunc = func
     return self
 end
 
 -- Get was looking
+---@return boolean
 function Spell:GetWasLooking()
     return self.wasLooking
 end
 
 -- Click the spell
+---@param x number
+---@param y number
+---@param z number
+---@return boolean
 function Spell:Click(x, y, z)
     if type(x) == 'table' then
         x, y, z = x.x, x.y, x.z
@@ -222,6 +256,8 @@ function Spell:Click(x, y, z)
 end
 
 -- Check if the spell is castable and cast it
+---@param unit Unit
+---@return boolean
 function Spell:Call(unit)
     if self:Castable() then
         self:Cast(unit)
@@ -230,11 +266,15 @@ function Spell:Call(unit)
     return false
 end
 
+-- Check if the spell is castable and cast it
+---@return boolean
 function Spell:HasRange()
     return SpellHasRange(self:GetName())
 end
 
 -- Check if the spell is in range of the unit
+---@param unit Unit
+---@return boolean
 function Spell:IsInRange(unit)
     local hasRange = self:HasRange()
     local inRange = IsSpellInRange(self:GetName(), unit:GetOMToken())
@@ -251,11 +291,13 @@ function Spell:IsInRange(unit)
 end
 
 -- Get the last cast time
+---@return number
 function Spell:GetLastCastTime()
     return self.lastCastAt
 end
 
 -- Get time since last cast
+---@return number
 function Spell:GetTimeSinceLastCast()
     if not self:GetLastCastTime() then
         return math.huge
@@ -264,10 +306,13 @@ function Spell:GetTimeSinceLastCast()
 end
 
 -- Get the spells charges
+---@return number
 function Spell:GetCharges()
     return GetSpellCharges(self:GetID())
 end
 
+-- Get the spells charges
+---@return number
 function Spell:GetChargesFractional()
     local charges, maxCharges, start, duration = GetSpellCharges(self:GetID())
 
@@ -288,12 +333,16 @@ function Spell:GetChargesFractional()
 end
 
 -- Get the spells charges remaining
+---@return number
 function Spell:GetChargesRemaining()
     local charges, maxCharges, start, duration = GetSpellCharges(self:GetID())
     return charges
 end
 
 -- Create a condition for the spell
+---@param name string
+---@param func fun(self:Spell):boolean
+---@return Spell
 function Spell:Condition(name, func)
     self.conditions[name] = {
         func = func
@@ -302,6 +351,8 @@ function Spell:Condition(name, func)
 end
 
 -- Get a condition for the spell
+---@param name string
+---@return function | nil
 function Spell:GetCondition(name)
     local condition = self.conditions[name]
     if condition then
@@ -312,6 +363,8 @@ function Spell:GetCondition(name)
 end
 
 -- Evaluate a condition for the spell
+---@param name string
+---@return boolean
 function Spell:EvaluateCondition(name)
     local condition = self:GetCondition(name)
     if condition then
@@ -322,6 +375,8 @@ function Spell:EvaluateCondition(name)
 end
 
 -- Check if the spell has a condition
+---@param name string
+---@return boolean
 function Spell:HasCondition(name)
     local condition = self:GetCondition(name)
     if condition then
@@ -332,17 +387,21 @@ function Spell:HasCondition(name)
 end
 
 -- Set the spells target
+---@param unit Unit
+---@return Spell
 function Spell:SetTarget(unit)
     self.target = unit
     return self
 end
 
 -- Get the spells target
+---@return Unit
 function Spell:GetTarget()
     return self.target
 end
 
 -- IsMagicDispel
+---@return boolean
 function Spell:IsMagicDispel()
     return ({
         [88423] = true
@@ -350,6 +409,7 @@ function Spell:IsMagicDispel()
 end
 
 -- IsCurseDispel
+---@return boolean
 function Spell:IsCurseDispel()
     return ({
         [88423] = true
@@ -357,6 +417,7 @@ function Spell:IsCurseDispel()
 end
 
 -- IsPoisonDispel
+---@return boolean
 function Spell:IsPoisonDispel()
     return ({
         [88423] = true
@@ -364,12 +425,16 @@ function Spell:IsPoisonDispel()
 end
 
 -- IsDiseaseDispel
+---@return boolean
 function Spell:IsDiseaseDispel()
     return ({
 
     })[self:GetID()]
 end
 
+-- IsSpell
+---@param spell Spell
+---@return boolean
 function Spell:IsSpell(spell)
     return self:GetID() == spell:GetID()
 end

src/Timer/Timer.lua

@@ -9,6 +9,8 @@ local Timer = {
 Timer.__index = Timer
 
 -- Constructor
+---@param type string
+---@return Timer
 function Timer:New(type)
     local self = setmetatable({}, Timer)
     self.startTime = nil
@@ -17,11 +19,13 @@ function Timer:New(type)
 end
 
 -- Start the timer
+---@return nil
 function Timer:Start()
     self.startTime = GetTime()
 end
 
 -- Get the time since the timer was started
+---@return number
 function Timer:GetTime()
     if not self:IsRunning() then
         return 0
@@ -30,11 +34,13 @@ function Timer:GetTime()
 end
 
 -- Check if the timer is running
+---@return boolean
 function Timer:IsRunning()
     return self.startTime ~= nil
 end
 
 -- Reset the timer
+---@return nil
 function Timer:Reset()
     self.startTime = nil
 end

src/Unit/Unit.lua

@@ -34,16 +34,21 @@ function Unit:__index(k)
 end
 
 -- Equals
+---@param other Unit
+---@return boolean
 function Unit:__eq(other)
     return UnitIsUnit(self:GetOMToken(), other.unit)
 end
 
 -- tostring
+---@return string
 function Unit:__tostring()
     return "Bastion.__Unit(" .. tostring(self:GetOMToken()) .. ")" .. " - " .. (self:GetName() or '')
 end
 
 -- Constructor
+---@param unit string
+---@return Unit
 function Unit:New(unit)
     local self              = setmetatable({}, Unit)
     self.unit               = unit
@@ -54,85 +59,107 @@ function Unit:New(unit)
 end
 
 -- Check if the unit is valid
+---@return boolean
 function Unit:IsValid()
     return self:GetOMToken() ~= nil and self:Exists()
 end
 
 -- Check if the unit exists
+---@return boolean
 function Unit:Exists()
     return Object(self:GetOMToken())
 end
 
 -- Get the units token
+---@return string
 function Unit:Token()
     return self:GetOMToken()
 end
 
 -- Get the units name
+---@return string
 function Unit:GetName()
     return UnitName(self:GetOMToken())
 end
 
 -- Get the units GUID
+---@return string
 function Unit:GetGUID()
     return ObjectGUID(self:GetOMToken())
 end
 
 -- Get the units health
+---@return number
 function Unit:GetHealth()
     return UnitHealth(self:GetOMToken())
 end
 
 -- Get the units max health
+---@return number
 function Unit:GetMaxHealth()
     return UnitHealthMax(self:GetOMToken())
 end
 
 -- Get the units health percentage
+---@return number
 function Unit:GetHP()
     return self:GetHealth() / self:GetMaxHealth() * 100
 end
 
+-- Get the units health deficit
+---@return number
 function Unit:GetHealthPercent()
     return self:GetHP()
 end
 
 -- Get the units power type
+---@return number
 function Unit:GetPowerType()
     return UnitPowerType(self:GetOMToken())
 end
 
 -- Get the units power
+---@param powerType number | nil
+---@return number
 function Unit:GetPower(powerType)
     local powerType = powerType or self:GetPowerType()
     return UnitPower(self:GetOMToken(), powerType)
 end
 
 -- Get the units max power
+---@param powerType number | nil
+---@return number
 function Unit:GetMaxPower(powerType)
     local powerType = powerType or self:GetPowerType()
     return UnitPowerMax(self:GetOMToken(), powerType)
 end
 
 -- Get the units power percentage
+---@param powerType number | nil
+---@return number
 function Unit:GetPP(powerType)
     local powerType = powerType or self:GetPowerType()
     return self:GetPower(powerType) / self:GetMaxPower(powerType) * 100
 end
 
 -- Get the units power deficit
+---@param powerType number | nil
+---@return number
 function Unit:GetPowerDeficit(powerType)
     local powerType = powerType or self:GetPowerType()
     return self:GetMaxPower(powerType) - self:GetPower(powerType)
 end
 
 -- Get the units position
+---@return Vector3
 function Unit:GetPosition()
     local x, y, z = ObjectPosition(self:GetOMToken())
     return Bastion.Vector3:New(x, y, z)
 end
 
 -- Get the units distance from another unit
+---@param unit Unit
+---@return number
 function Unit:GetDistance(unit)
     local pself = self:GetPosition()
     local punit = unit:GetPosition()
@@ -141,36 +168,43 @@ function Unit:GetDistance(unit)
 end
 
 -- Is the unit dead
+---@return boolean
 function Unit:IsDead()
     return UnitIsDeadOrGhost(self:GetOMToken())
 end
 
 -- Is the unit alive
+---@return boolean
 function Unit:IsAlive()
     return not UnitIsDeadOrGhost(self:GetOMToken())
 end
 
 -- Is the unit a pet
+---@return boolean
 function Unit:IsPet()
     return UnitIsUnit(self:GetOMToken(), "pet")
 end
 
 -- Is the unit a friendly unit
+---@return boolean
 function Unit:IsFriendly()
     return UnitIsFriend("player", self:GetOMToken())
 end
 
 -- IsEnemy
+---@return boolean
 function Unit:IsEnemy()
     return UnitCanAttack("player", self:GetOMToken())
 end
 
 -- Is the unit a hostile unit
+---@return boolean
 function Unit:IsHostile()
     return UnitCanAttack(self:GetOMToken(), 'player')
 end
 
 -- Is the unit a boss
+---@return boolean
 function Unit:IsBoss()
     if UnitClassification(self:GetOMToken()) == "worldboss" then
         return true
@@ -187,6 +221,7 @@ function Unit:IsBoss()
     return false
 end
 
+---@return string
 function Unit:GetOMToken()
     if not self.unit then
         return "none"
@@ -195,51 +230,61 @@ function Unit:GetOMToken()
 end
 
 -- Is the unit a target
+---@return boolean
 function Unit:IsTarget()
     return UnitIsUnit(self:GetOMToken(), "target")
 end
 
 -- Is the unit a focus
+---@return boolean
 function Unit:IsFocus()
     return UnitIsUnit(self:GetOMToken(), "focus")
 end
 
 -- Is the unit a mouseover
+---@return boolean
 function Unit:IsMouseover()
     return UnitIsUnit(self:GetOMToken(), "mouseover")
 end
 
 -- Is the unit a tank
+---@return boolean
 function Unit:IsTank()
     return UnitGroupRolesAssigned(self:GetOMToken()) == "TANK"
 end
 
 -- Is the unit a healer
+---@return boolean
 function Unit:IsHealer()
     return UnitGroupRolesAssigned(self:GetOMToken()) == "HEALER"
 end
 
 -- Is the unit a damage dealer
+---@return boolean
 function Unit:IsDamage()
     return UnitGroupRolesAssigned(self:GetOMToken()) == "DAMAGER"
 end
 
 -- Is the unit a player
+---@return boolean
 function Unit:IsPlayer()
     return UnitIsPlayer(self:GetOMToken())
 end
 
 -- Is the unit a player controlled unit
+---@return boolean
 function Unit:IsPCU()
     return UnitPlayerControlled(self:GetOMToken())
 end
 
 -- Get if the unit is affecting combat
+---@return boolean
 function Unit:IsAffectingCombat()
     return UnitAffectingCombat(self:GetOMToken())
 end
 
 -- Get the units class id
+---@return Class
 function Unit:GetClass()
     local locale, class, classID = UnitClass(self:GetOMToken())
     return Bastion.Class:New(locale, class, classID)
@@ -252,6 +297,7 @@ function Unit:GetAuras()
 end
 
 -- Get the raw unit
+---@return string
 function Unit:GetRawUnit()
     return self:GetOMToken()
 end
@@ -266,6 +312,8 @@ local isClassicWow = select(4, GetBuildInfo()) < 40000
 local losFlag = bit.bor(0x1, 0x10, 0x100000)
 
 -- Check if the unit can see another unit
+---@param unit Unit
+---@return boolean
 function Unit:CanSee(unit)
     -- mechagon smoke cloud
     -- local mechagonID = 2097
@@ -311,11 +359,13 @@ function Unit:CanSee(unit)
 end
 
 -- Check if the unit is casting a spell
+---@return boolean
 function Unit:IsCasting()
     return UnitCastingInfo(self:GetOMToken()) ~= nil
 end
 
 -- Get Casting or channeling spell
+---@return Spell | nil
 function Unit:GetCastingOrChannelingSpell()
     local name, text, texture, startTimeMS, endTimeMS, isTradeSkill, castID, notInterruptible, spellId = UnitCastingInfo(self
         .unit)
@@ -333,20 +383,25 @@ function Unit:GetCastingOrChannelingSpell()
 end
 
 -- Check if the unit is channeling a spell
+---@return boolean
 function Unit:IsChanneling()
     return UnitChannelInfo(self:GetOMToken()) ~= nil
 end
 
 -- Check if the unit is casting or channeling a spell
+---@return boolean
 function Unit:IsCastingOrChanneling()
     return self:IsCasting() or self:IsChanneling()
 end
 
 -- Check if the unit can attack the target
+---@param unit Unit
+---@return boolean
 function Unit:CanAttack(unit)
     return UnitCanAttack(self:GetOMToken(), unit:GetOMToken())
 end
 
+---@return number
 function Unit:GetChannelOrCastPercentComplete()
     local name, text, texture, startTimeMS, endTimeMS, isTradeSkill, castID, notInterruptible, spellId = UnitCastingInfo(self
         .unit)
@@ -366,6 +421,8 @@ function Unit:GetChannelOrCastPercentComplete()
     return 0
 end
 
+-- Check if unit is interruptible
+---@return boolean
 function Unit:IsInterruptible()
     local name, text, texture, startTimeMS, endTimeMS, isTradeSkill, castID, notInterruptible, spellId = UnitCastingInfo(self
         .unit)
@@ -383,6 +440,8 @@ function Unit:IsInterruptible()
 end
 
 -- Check if unit is interruptible
+---@param percent number
+---@return boolean
 function Unit:IsInterruptibleAt(percent)
     if not self:IsInterruptible() then
         return false
@@ -399,6 +458,8 @@ function Unit:IsInterruptibleAt(percent)
 end
 
 -- Get the number of enemies in a given range of the unit and cache the result for .5 seconds
+---@param range number
+---@return number
 function Unit:GetEnemies(range)
     local enemies = self.cache:Get("enemies_" .. range)
     if enemies then
@@ -419,6 +480,7 @@ function Unit:GetEnemies(range)
 end
 
 -- Get the number of melee attackers
+---@return number
 function Unit:GetMeleeAttackers()
     local enemies = self.cache:Get("melee_attackers")
     if enemies then
@@ -438,6 +500,9 @@ function Unit:GetMeleeAttackers()
     return count
 end
 
+---@param distance number
+---@param percent number
+---@return number
 function Unit:GetPartyHPAround(distance, percent)
     local count = 0
 
@@ -452,33 +517,43 @@ function Unit:GetPartyHPAround(distance, percent)
 end
 
 -- Is moving
+---@return boolean
 function Unit:IsMoving()
     return GetUnitSpeed(self:GetOMToken()) > 0
 end
 
+-- Is moving at all
+---@return boolean
 function Unit:IsMovingAtAll()
     return ObjectMovementFlag(self:GetOMToken()) ~= 0
 end
 
+---@return number
 function Unit:GetComboPoints()
     return UnitPower(self:GetOMToken(), 4)
 end
 
+---@return number
 function Unit:GetComboPointsMax()
     return UnitPowerMax(self:GetOMToken(), 4)
 end
 
 -- Get combopoints deficit
+---@return number
 function Unit:GetComboPointsDeficit()
     return self:GetComboPointsMax() - self:GetComboPoints()
 end
 
 -- IsUnit
+---@param unit Unit
+---@return boolean
 function Unit:IsUnit(unit)
     return UnitIsUnit(self:GetOMToken(), unit and unit:GetOMToken() or 'none')
 end
 
 -- IsTanking
+---@param unit Unit
+---@return boolean
 function Unit:IsTanking(unit)
     local isTanking, status, threatpct, rawthreatpct, threatvalue = UnitDetailedThreatSituation(self:GetOMToken(),
         unit:GetOMToken())
@@ -486,6 +561,8 @@ function Unit:IsTanking(unit)
 end
 
 -- IsFacing
+---@param unit Unit
+---@return boolean
 function Unit:IsFacing(unit)
     local rot = ObjectRotation(self:GetOMToken())
     local x, y, z = ObjectPosition(self:GetOMToken())
@@ -506,6 +583,8 @@ function Unit:IsFacing(unit)
 end
 
 -- IsBehind
+---@param unit Unit
+---@return boolean
 function Unit:IsBehind(unit)
     local rot = ObjectRotation(unit:GetOMToken())
     local x, y, z = ObjectPosition(unit:GetOMToken())
@@ -525,6 +604,7 @@ function Unit:IsBehind(unit)
     return math.abs(angle) > 90
 end
 
+---@return number
 function Unit:GetMeleeBoost()
     if IsPlayerSpell(196924) then
         return 3
@@ -540,6 +620,8 @@ end
 -- return ((myPos.x - targetPos.x) * (myPos.x - targetPos.x)) + ((myPos.y - targetPos.y) * (myPos.y - targetPos.y)) + ((myPos.z - targetPos.z) * (myPos.z - targetPos.z)) <= (float)(fMaxDist * fMaxDist);
 
 -- InMelee
+---@param unit Unit
+---@return boolean
 function Unit:InMelee(unit)
     local x, y, z = ObjectPosition(self:GetOMToken())
     local x2, y2, z2 = ObjectPosition(unit:GetOMToken())
@@ -556,16 +638,21 @@ function Unit:InMelee(unit)
 end
 
 -- Get object id
+---@return number
 function Unit:GetID()
     return ObjectID(self:GetOMToken())
 end
 
 -- In party
+---@return boolean
 function Unit:IsInParty()
     return UnitInParty(self:GetOMToken())
 end
 
 -- Linear regression between time and percent to something
+---@param time table
+---@param percent table
+---@return number, number
 function Unit:LinearRegression(time, percent)
     local x = time
     local y = percent
@@ -592,6 +679,8 @@ function Unit:LinearRegression(time, percent)
 end
 
 -- Use linear regression to get the health percent at a given time in the future
+---@param time number
+---@return number
 function Unit:PredictHealth(time)
     local x = {}
     local y = {}
@@ -613,6 +702,8 @@ function Unit:PredictHealth(time)
 end
 
 -- Use linear regression to guess the time until a given health percent
+---@param percent number
+---@return number
 function Unit:PredictTime(percent)
     local x = {}
     local y = {}
@@ -634,6 +725,7 @@ function Unit:PredictTime(percent)
 end
 
 -- Time until death
+---@return number
 function Unit:TimeToDie()
     if self:IsDead() then
         self.regression_history = {}
@@ -650,16 +742,21 @@ function Unit:TimeToDie()
 end
 
 -- Set combat time if affecting combat and return the difference between now and the last time
+---@return number
 function Unit:GetCombatTime()
     return GetTime() - self.last_combat_time
 end
 
+-- Set last combat time
+---@param time number
+---@return nil
 function Unit:SetLastCombatTime(time)
     self.last_combat_time = time
 end
 
 -- Get combat odds (if the last combat time is less than 1 minute ago return 1 / time, else return 0)
 -- the closer to 0 the more likely the unit is to be in combat (0 = 100%) 60 = 0%
+---@return number
 function Unit:InCombatOdds()
     local time = self:GetCombatTime()
     local percent = 1 - (time / 60)
@@ -668,6 +765,7 @@ function Unit:InCombatOdds()
 end
 
 -- Get units gcd time
+---@return number
 function Unit:GetGCD()
     local start, duration = GetSpellCooldown(61304)
     if start == 0 then
@@ -686,6 +784,7 @@ The GCD won't drop below 1 second
 More than 50% Haste will drop a spell below 1 second
 
 ]]
+---@return number
 function Unit:GetMaxGCD()
     local haste = UnitSpellHaste(self:GetOMToken())
     if haste > 50 then
@@ -696,6 +795,7 @@ function Unit:GetMaxGCD()
 end
 
 -- IsStealthed
+---@return boolean
 function Unit:IsStealthed()
     local Stealth = Bastion.SpellBook:GetSpell(1784)
     local Vanish = Bastion.SpellBook:GetSpell(1856)
@@ -709,6 +809,7 @@ function Unit:IsStealthed()
 end
 
 -- Get unit swing timers
+---@return number, number
 function Unit:GetSwingTimers()
     local main_speed, off_speed = UnitAttackSpeed(self:GetOMToken())
     local main_speed = main_speed or 2
@@ -728,6 +829,7 @@ function Unit:GetSwingTimers()
     return main_speed_remains, off_speed_remains
 end
 
+---@return nil
 function Unit:WatchForSwings()
     Bastion.EventManager:RegisterWoWEvent("COMBAT_LOG_EVENT_UNFILTERED", function()
         local _, subtype, _, sourceGUID, sourceName, _, _, destGUID, destName, destFlags, _, spellID, spellName, _, amount, interrupt, a, b, c, d, offhand, multistrike = CombatLogGetCurrentEventInfo()

src/UnitManager/UnitManager.lua

@@ -99,6 +99,7 @@ function UnitManager:__index(k)
 end
 
 -- Constructor
+---@return UnitManager
 function UnitManager:New()
     local self = setmetatable({}, UnitManager)
     self.units = {}
@@ -112,6 +113,7 @@ function UnitManager:Validate(token)
 end
 
 -- Get or create a unit
+---@param token string
 ---@return Unit
 function UnitManager:Get(token)
     -- if not Validate(token) then
@@ -142,10 +144,16 @@ function UnitManager:Get(token)
     end)
 end
 
+-- Get a unit by guid
+---@param guid string
+---@return Unit
 function UnitManager:GetObject(guid)
     return self.objects[guid]
 end
 
+-- Set a unit by guid
+---@param unit Unit
+---@return Unit
 function UnitManager:SetObject(unit)
     self.objects[unit:GetGUID()] = unit
 end
@@ -175,6 +183,8 @@ function UnitManager:CreateCustomUnit(token, cb)
 end
 
 -- Enum Friends (party/raid members)
+---@param cb fun(unit: Unit):boolean
+---@return nil
 function UnitManager:EnumFriends(cb)
     Bastion.ObjectManager.friends:each(function(unit)
         if cb(unit) then
@@ -185,6 +195,7 @@ end
 
 -- Enum Enemies (object manager)
 ---@param cb fun(unit: Unit):boolean
+---@return nil
 function UnitManager:EnumEnemies(cb)
     Bastion.ObjectManager.activeEnemies:each(function(unit)
         if cb(unit) then
@@ -194,6 +205,8 @@ function UnitManager:EnumEnemies(cb)
 end
 
 -- Enum Units (object manager)
+---@param cb fun(unit: Unit):boolean
+---@return nil
 function UnitManager:EnumUnits(cb)
     Bastion.ObjectManager.enemies:each(function(unit)
         if cb(unit) then
@@ -203,6 +216,8 @@ function UnitManager:EnumUnits(cb)
 end
 
 -- Get the number of friends with a buff (party/raid members)
+---@param spell Spell
+---@return number
 function UnitManager:GetNumFriendsWithBuff(spell)
     local count = 0
     self:EnumFriends(function(unit)
@@ -214,6 +229,7 @@ function UnitManager:GetNumFriendsWithBuff(spell)
 end
 
 -- Get the number of friends alive (party/raid members)
+---@return number
 function UnitManager:GetNumFriendsAlive()
     local count = 0
     self:EnumFriends(function(unit)
@@ -225,7 +241,9 @@ function UnitManager:GetNumFriendsAlive()
 end
 
 -- Get the friend with the most friends within a given radius (party/raid members)
--- Return unit, friends
+---@param radius number
+---@return Unit
+---@return table
 function UnitManager:GetFriendWithMostFriends(radius)
     local unit = nil
     local count = 0
@@ -254,6 +272,9 @@ function UnitManager:GetFriendWithMostFriends(radius)
 end
 
 -- Find the centroid of the most dense area of friends (party/raid members) of a given radius within a given range
+---@param radius number
+---@param range number
+---@return Vector3 | nil
 function UnitManager:FindFriendsCentroid(radius, range)
     local unit, friends = self:GetFriendWithMostFriends(radius)
     if unit == nil then

src/Vector3/Vector3.lua

@@ -4,14 +4,19 @@
 local Vector3 = {}
 Vector3.__index = Vector3
 
+---@return string
 function Vector3:__tostring()
     return "Vector3(" .. self.x .. ", " .. self.y .. ", " .. self.z .. ")"
 end
 
+---@param other Vector3
+---@return Vector3
 function Vector3:__add(other)
     return Vector3:New(self.x + other.x, self.y + other.y, self.z + other.z)
 end
 
+---@param other Vector3
+---@return Vector3
 function Vector3:__sub(other)
     if type(other) == "number" then
         return Vector3:New(self.x - other, self.y - other, self.z - other)
@@ -19,30 +24,42 @@ function Vector3:__sub(other)
     return Vector3:New(self.x - other.x, self.y - other.y, self.z - other.z)
 end
 
+---@param other number
+---@return Vector3
 function Vector3:__mul(other)
     return Vector3:New(self.x * other, self.y * other, self.z * other)
 end
 
+---@param other number
+---@return Vector3
 function Vector3:__div(other)
     return Vector3:New(self.x / other, self.y / other, self.z / other)
 end
 
+---@param other Vector3
+---@return boolean
 function Vector3:__eq(other)
     return self.x == other.x and self.y == other.y and self.z == other.z
 end
 
+---@param other Vector3
+---@return boolean
 function Vector3:__lt(other)
     return self.x < other.x and self.y < other.y and self.z < other.z
 end
 
+---@param other Vector3
+---@return boolean
 function Vector3:__le(other)
     return self.x <= other.x and self.y <= other.y and self.z <= other.z
 end
 
+---@return Vector3
 function Vector3:__unm()
     return Vector3:New(-self.x, -self.y, -self.z)
 end
 
+---@return number
 function Vector3:__len()
     return math.sqrt(self.x * self.x + self.y * self.y + self.z * self.z)
 end
@@ -152,6 +169,10 @@ function Vector3:__newindex(k, v)
     end
 end
 
+---@param x number
+---@param y number
+---@param z number
+---@return Vector3
 function Vector3:New(x, y, z)
     if x == false then
         return Vector3:New(0, 0, 0)
@@ -161,18 +182,26 @@ function Vector3:New(x, y, z)
     return self
 end
 
+---@param rhs Vector3
+---@return number
 function Vector3:Dot(rhs)
     return self.x * rhs.x + self.y * rhs.y + self.z * rhs.z
 end
 
+---@param rhs Vector3
+---@return Vector3
 function Vector3:Cross(rhs)
     return Vector3:New(self.y * rhs.z - self.z * rhs.y, self.z * rhs.x - self.x * rhs.z, self.x * rhs.y - self.y * rhs.x)
 end
 
+---@param b Vector3
+---@return number
 function Vector3:Distance(b)
     return FastDistance(self.x, self.y, self.z, b.x, b.y, b.z)
 end
 
+---@param to Vector3
+---@return number
 function Vector3:Angle(to)
     return math.acos(self:Dot(to) /
         (
@@ -180,6 +209,8 @@ function Vector3:Angle(to)
             math.sqrt(to.x * to.x + to.y * to.y + to.z * to.z)))
 end
 
+---@param maxLength number
+---@return Vector3
 function Vector3:ClampMagnitude(maxLength)
     if self:Dot(self) > maxLength * maxLength then
         return self.normalized * maxLength
@@ -189,15 +220,25 @@ function Vector3:ClampMagnitude(maxLength)
 end
 
 -- Implement a clamp function
+---@param x number
+---@param min number
+---@param max number
+---@return number
 local function clamp(x, min, max)
     return x < min and min or (x > max and max or x)
 end
 
+---@param b Vector3
+---@param t number
+---@return Vector3
 function Vector3:Lerp(b, t)
     t = clamp(t, 0, 1)
     return Vector3:New(self.x + (b.x - self.x) * t, self.y + (b.y - self.y) * t, self.z + (b.z - self.z) * t)
 end
 
+---@param target Vector3
+---@param maxDistanceDelta number
+---@return Vector3
 function Vector3:MoveTowards(target, maxDistanceDelta)
     local toVector = target - self
     local distance = toVector.magnitude
@@ -208,10 +249,14 @@ function Vector3:MoveTowards(target, maxDistanceDelta)
     return self + toVector / distance * maxDistanceDelta
 end
 
+---@param b Vector3
+---@return Vector3
 function Vector3:Scale(b)
     return Vector3:New(self.x * b.x, self.y * b.y, self.z * b.z)
 end
 
+---@param onNormal Vector3
+---@return Vector3
 function Vector3:Project(onNormal)
     local num = onNormal:Dot(onNormal)
     if num < 1.401298E-45 then
@@ -221,14 +266,19 @@ function Vector3:Project(onNormal)
     return onNormal * self:Dot(onNormal) / num
 end
 
+---@param planeNormal Vector3
+---@return Vector3
 function Vector3:ProjectOnPlane(planeNormal)
     return self - self:Project(planeNormal)
 end
 
+---@param inDirection Vector3
+---@return Vector3
 function Vector3:Reflect(inNormal)
     return -2 * inNormal:Dot(self) * inNormal + self
 end
 
+---@return Vector3
 function Vector3:Normalize()
     local num = self:Dot(self)
     if num > 1E-05 then