Enhance UnitBuff documentation with detailed parameter and return type annotations

api/UnitBuff.lua

@@ -1,37 +1,40 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param unit string
----@param index number
----@param name string
----@param rank string
----@param filter RAID
----@param CANCELABLE
----@param NOT_CANCELABLE
----@param PLAYER
----@param RAID
----@return string name
----@return string rank
----@return string icon
----@return number count
----@return Poison dispelType
----@return  Curse
----@return  Disease
----@return  Magic
----@return  Poison
----@return number duration
----@return number expires
----@return string caster
----@return boolean isStealable
----@return boolean nameplateShowPersonal
----@return number spellID
----@return boolean canApplyAura
----@return boolean isBossDebuff
----@return boolean _
----@return boolean nameplateShowAll
----@return number timeMod
----@return number value1
----@return number value2
----@return number value3
----Returns information about a buff on a unit. This function is an alias for UnitAura() with a built-in HELPFUL filter (which cannot be removed or negated with the HARMFUL filter).
-function UnitBuff(unit, index, name, rank, filter, CANCELABLE, NOT_CANCELABLE, PLAYER, RAID) end
+---@enum BuffFilter
+---| 'CANCELABLE'
+---| 'NOT_CANCELABLE'
+---| 'PLAYER'
+---| 'RAID'
+---@enum DispellType
+---| 'POISON'
+---| 'DISEASE'
+---| 'CURSE'
+---| 'MAGIC'
+
+---@param unit string The unit to query (e.g., "player", "target").
+---@param index number The index of the aura to query (1-based).
+---@param name string The name of the aura to query.
+---@param rank string The rank of the aura (e.g., "Rank 7").
+---@param filter BuffFilter A filter to specify which auras to return (e.g., "PLAYER|RAID").
+---@return string #name The name of the aura.
+---@return string #rank The rank of the aura, if applicable.
+---@return string #icon The path to the icon texture for the aura.
+---@return number #count The number of times the aura has been applied.
+---@return DispellType #dispelType The type of aura (e.g., "POISON", "MAGIC").
+---@return number #duration The total duration of the aura in seconds.
+---@return number #expires The time at which the aura will expire.
+---@return string #caster The unit that applied the aura.
+---@return boolean #isStealable True if the aura can be stolen.
+---@return boolean #nameplateShowPersonal True if the aura is visible above nameplates for the caster.
+---@return number #spellID The spell ID of the aura.
+---@return boolean #canApplyAura True if the player can apply the aura.
+---@return boolean #isBossDebuff True if the aura was cast by a boss.
+---@return boolean _ Unknown parameter.
+---@return boolean nameplateShowAll True if the aura is visible above nameplates for all players.
+---@return number timeMod The modified time remaining on the aura.
+---@return number value1 Value of variable effect 1 of the aura.
+---@return number value2 Value of variable effect 2 of the aura.
+---@return number value3 Value of variable effect 3 of the aura.
+--- Returns information about a buff on a unit. This function is an alias for UnitAura() with a built-in HELPFUL filter.
+function UnitBuff(unit, index, name, rank, filter) end