Refactor API functions to improve parameter aliasing and enhance documentation clarity

api/GetRuneType.lua

@@ -1,17 +1,21 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param slot 6 
+---@alias runeSlot
----@param 1  
+---| 1 - Leftmost
----@param 2  
+---| 2 - Second from left
----@param 3  
+---| 3 - Fifth from left (second from right)
----@param 4  
+---| 4 - Sixth from left (rightmost)
----@param 5  
+---| 5 - Third from left
----@param 6  
+---| 6 - Fourth from left
----@return 4 runeType 
+
----@return  1 
+---@alias runeType
----@return  2 
+---| 1 - Blood rune
----@return  3 
+---| 2 - Unholy rune
----@return  4 
+---| 3 - Frost rune
+---| 4 - Death rune
+
+---@param slot runeSlot
+---@return runeType runeType
 ---Returns the type of one of the player's rune resources. Note the placement of runes 3-4 (normally Unholy) and 5-6 (normally Frost) are reversed in the default UI.
-function GetRuneType(slot, 1, 2, 3, 4, 5, 6) end
+function GetRuneType(slot) end

api/GetSpellBonusDamage.lua

@@ -1,14 +1,7 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param school 7 
+---@param school spellSchool
----@param 1  
+---@return number minModifier
----@param 2  
----@param 3  
----@param 4  
----@param 5  
----@param 6  
----@param 7  
----@return number minModifier 
 ---Returns the player's spell damage bonus for a spell school
-function GetSpellBonusDamage(school, 1, 2, 3, 4, 5, 6, 7) end
+function GetSpellBonusDamage(school) end

api/GetSpellCritChance.lua

@@ -1,14 +1,16 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param school 7 
+---@alias spellSchool
----@param 1  
+---| 1 - Physical
----@param 2  
+---| 2 - Holy
----@param 3  
+---| 3 - Fire
----@param 4  
+---| 4 - Nature
----@param 5  
+---| 5 - Frost
----@param 6  
+---| 6 - Shadow
----@param 7  
+---| 7 - Arcane
----@return number minCrit 
+
+---@param school spellSchool
+---@return number minCrit
 ---Returns the player's spell critical strike chance for a spell school
-function GetSpellCritChance(school, 1, 2, 3, 4, 5, 6, 7) end
+function GetSpellCritChance(school) end

api/GetStablePetFoodTypes.lua

@@ -1,9 +1,7 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param index 1 to NUM_PET_STABLE_SLOTS 
+---@param index number
----@param 0  
+---@return string[] foodTypes
----@param 1 to NUM_PET_STABLE_SLOTS  
----@return list ... 
 ---Returns the types of food that a stabled pet will eat
-function GetStablePetFoodTypes(index, 0, 1 to NUM_PET_STABLE_SLOTS) end
+function GetStablePetFoodTypes(index) end

api/GetStablePetInfo.lua

@@ -1,13 +1,11 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param index 1 to NUM_PET_STABLE_SLOTS 
+---@param index number
----@param 0  
+---@return string icon
----@param 1 to NUM_PET_STABLE_SLOTS  
+---@return string name
----@return string icon 
+---@return number level
----@return string name 
+---@return string family
----@return number level 
+---@return string talent
----@return string family 
----@return string talent 
 ---Returns information about a stabled pet
-function GetStablePetInfo(index, 0, 1 to NUM_PET_STABLE_SLOTS) end
+function GetStablePetInfo(index) end

api/GetTalentLink.lua

@@ -1,14 +1,11 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param tabIndex number 
+---@param tabIndex number
----@param talentIndex number 
+---@param talentIndex number
----@param inspect boolean 
+---@param inspect boolean
----@param pet boolean 
+---@param pet boolean
----@param talentGroup nil 
+---@param talentGroup talentGroup
----@param 1  
+---@return string link
----@param 2  
----@param nil  
----@return string link 
 ---Returns a hyperlink for a talent
-function GetTalentLink(tabIndex, talentIndex, inspect, pet, talentGroup, 1, 2, nil) end
+function GetTalentLink(tabIndex, talentIndex, inspect, pet, talentGroup) end

api/GetTotemInfo.lua

@@ -1,15 +1,11 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param slot 4 
+---@param slot totemSlot
----@param 1  
+---@return boolean haveTotem
----@param 2  
+---@return string name
----@param 3  
+---@return number startTime
----@param 4  
+---@return number duration
----@return boolean haveTotem 
+---@return string icon
----@return string name 
----@return number startTime 
----@return number duration 
----@return string icon 
 ---Returns information on a currently active totem (or ghoul). Totem functions are also used for ghouls summoned by a Death Knight's Raise Dead ability (if the ghoul is not made a controllable pet by the Master of Ghouls talent), for druids' wild mushrooms, and Affliction Warlock's Soul Effigy.
-function GetTotemInfo(slot, 1, 2, 3, 4) end
+function GetTotemInfo(slot) end

api/GetTotemTimeLeft.lua

@@ -1,11 +1,7 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param slot 4 
+---@param slot totemSlot
----@param 1  
+---@return number seconds
----@param 2  
----@param 3  
----@param 4  
----@return number seconds 
 ---Returns the time remaining before a totem (or ghoul) automatically disappears. Using GetTime() and the third and fourth returns (startTime and duration) of GetTotemInfo() instead of this function is recommended if frequent updates are needed. Totem functions are also used for ghouls summoned by a Death Knight's Raise Dead ability (if the ghoul is not made a controllable pet by the Master of Ghouls talent).
-function GetTotemTimeLeft(slot, 1, 2, 3, 4) end
+function GetTotemTimeLeft(slot) end

api/GetWorldPVPAreaInfo.lua

@@ -1,14 +1,16 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param pvpMapID 2 
+---@alias pvpMapID
----@param 1  
+---| 1 - Wintergrasp
----@param 2  
+---| 2 - Tol Barad
----@return number pvpID 
+
----@return string localizedName 
+---@param pvpMapID pvpMapID
----@return boolean isActive 
+---@return number pvpID
----@return boolean canQueue 
+---@return string localizedName
----@return number waitTime 
+---@return boolean isActive
----@return boolean canEnter 
+---@return boolean canQueue
+---@return number waitTime
+---@return boolean canEnter
 ---Returns information about a given world PvP zone
-function GetWorldPVPAreaInfo(pvpMapID, 1, 2) end
+function GetWorldPVPAreaInfo(pvpMapID) end

api/GuildControlSetRankFlag.lua

@@ -1,23 +1,25 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param index 17 
+---@alias guildControlRankFlag
----@param 1  
+---| 1 - Guildchat listen
----@param 2  
+---| 2 - Guildchat speak
----@param 3  
+---| 3 - Officerchat listen
----@param 4  
+---| 4 - Officerchat speak
----@param 5  
+---| 5 - Promote
----@param 6  
+---| 6 - Demote
----@param 7  
+---| 7 - Invite Member
----@param 8  
+---| 8 - Remove Member
----@param 9  
+---| 9 - Set MOTD
----@param 10  
+---| 10 - Edit Public Notes
----@param 11  
+---| 11 - View Officer Note
----@param 12  
+---| 12 - Edit Officer Note
----@param 13  
+---| 13 - Modify Guild Info
----@param 15  
+---| 15 - Use guild funds for repairs
----@param 16  
+---| 16 - Withdraw gold from the guild bank
----@param 17  
+---| 17 - Create Guild Event
----@param enabled boolean 
+
+---@param index guildControlRankFlag
+---@param enabled boolean
 ---Enables or disables a privilege for the guild rank being edited. Changes are not saved until a call is made to GuildControlSaveRank().
-function GuildControlSetRankFlag(index, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 17, enabled) end
+function GuildControlSetRankFlag(index, enabled) end

api/IsMouseButtonDown.lua

@@ -1,12 +1,14 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param button 5 or Button5 
+---@alias mouseButton
----@param 1 or LeftButton  
+---| 1 or "LeftButton" - Primary mouse button
----@param 2 or RightButton  
+---| 2 or "RightButton" - Secondary mouse button
----@param 3 or MiddleButton  
+---| 3 or "MiddleButton" - Third mouse button (or clickable scroll control)
----@param 4 or Button4  
+---| 4 or "Button4" - Fourth mouse button
----@param 5 or Button5  
+---| 5 or "Button5" - Fifth mouse button
----@return 1nil isDown 
+
+---@param button mouseButton
+---@return boolean isDown
 ---Returns whether a given mouse button is held down. If no button is specified, returns 1 if any mouse button is held down.
-function IsMouseButtonDown(button, 1 or LeftButton, 2 or RightButton, 3 or MiddleButton, 4 or Button4, 5 or Button5) end
+function IsMouseButtonDown(button) end

api/KBArticle_BeginLoading.lua

@@ -1,9 +1,11 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param articleId number 
+---@alias searchType
----@param searchType 2 
+---| 1 - Default "top issues" search
----@param 1  
+---| 2 - Search for specific text
----@param 2  
+
+---@param articleId number
+---@param searchType searchType
 ---Requests a specific knowledge base article from the server
-function KBArticle_BeginLoading(articleId, searchType, 1, 2) end
+function KBArticle_BeginLoading(articleId, searchType) end

api/LearnTalent.lua

@@ -1,12 +1,14 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param tabIndex number 
+---@alias talentGroup
----@param talentIndex number 
+---| 1 - Primary Talents
----@param isPet boolean 
+---| 2 - Secondary Talents
----@param talentGroup nil 
+---| nil - Currently active talents
----@param 1  
+
----@param 2  
+---@param tabIndex number
----@param nil  
+---@param talentIndex number
+---@param isPet boolean
+---@param talentGroup talentGroup
 ---Learns a talent, spending one talent point
-function LearnTalent(tabIndex, talentIndex, isPet, talentGroup, 1, 2, nil) end
+function LearnTalent(tabIndex, talentIndex, isPet, talentGroup) end

api/LoadBindings.lua

@@ -1,9 +1,11 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param set 2 
+---@alias bindingSet
----@param 0  
+---| 0 - Default key bindings
----@param 1  
+---| 1 - Account-wide key bindings
----@param 2  
+---| 2 - Character-specific key bindings
+
+---@param set bindingSet
 ---Loads a set of key bindings. The UPDATE_BINDINGS event fires when the new bindings have taken effect.
-function LoadBindings(set, 0, 1, 2) end
+function LoadBindings(set) end

api/MovieRecording_IsCodecSupported.lua

@@ -1,11 +1,13 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param codecID 1836070006 
+---@alias codecID
----@param 1635148593  
+---| 1635148593 - H.264 - supported natively by Apple devices like the iPod, iPhone and AppleTV; best ratio quality/size but slowest to compress
----@param 1768124260  
+---| 1768124260 - Apple Intermediate Codec - fastest to compress, but exclusive to Mac OS X
----@param 1835692129  
+---| 1835692129 - Motion JPEG - faster to compress than H.264 but it will generate a bigger file
----@param 1836070006  
+---| 1836070006 - MPEG-4 - supported by many digital cameras and iMovie
----@return boolean isSupported 
+
+---@param codecID codecID
+---@return boolean isSupported
 ---Returns whether a video codec is supported on the current system
-function MovieRecording_IsCodecSupported(codecID, 1635148593, 1768124260, 1835692129, 1836070006) end
+function MovieRecording_IsCodecSupported(codecID) end

api/PickupStablePet.lua

@@ -1,8 +1,6 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param index 1 to NUM_PET_STABLE_SLOTS 
+---@param index number #0 for active pet otherwise 1 to NUM_PET_STABLE_SLOTS
----@param 0  
----@param 1 to NUM_PET_STABLE_SLOTS  
 ---Puts a pet from the stables onto the cursor. Use with ClickStablePet to move pets between stabled and active status.
-function PickupStablePet(index, 0, 1 to NUM_PET_STABLE_SLOTS) end
+function PickupStablePet(index) end

api/RespondInstanceLock.lua

@@ -1,8 +1,6 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param response true 
+---@param response boolean
----@param false  
+---Allows leaving a recently entered instance to which the player would otherwise be saved. Applies when the player enters an instance to which other members of her group are saved; if the player leaves the within the time limit (see GetInstanceLockTimeRemaining()) she will not be saved to the instance.
----@param true  
+function RespondInstanceLock(response) end
----Allows leaving a recently entered instance to which the player would otherwise be saved.    Applies when the player enters an instance to which other members of her group are saved; if the player leaves the within the time limit (see GetInstanceLockTimeRemaining()) she will not be saved to the instance.
-function RespondInstanceLock(response, false, true) end

api/RollOnLoot.lua

@@ -1,11 +1,13 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param id number 
+---@alias rollType number
----@param rollType 3 
+---| 0 - Pass (declines the loot)
----@param 0  
+---| 1 - Roll "need" (wins if highest roll)
----@param 1  
+---| 2 - Roll "greed" (wins if highest roll and no other member rolls "need")
----@param 2  
+---| 3 - Disenchant
----@param 3  
+
+---@param id number
+---@param rollType rollType
 ---Register the player's intent regarding an item up for loot rolling. Rolls are not actually performed until all eligible group members have registered their intent or the time period for rolling expires. If the item binds on pickup, the CONFIRM_LOOT_ROLL event fires, indicating that ConfirmLootRoll(id) must be called in order to actually roll on the item.
-function RollOnLoot(id, rollType, 0, 1, 2, 3) end
+function RollOnLoot(id, rollType) end

api/RunMacro.lua

@@ -1,8 +1,8 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param index number 
+---@param index number
----@param name string 
+---@param name string
----@param "button" string 
+---@param button string
 ---Runs a macro
-function RunMacro(index, name, "button") end
+function RunMacro(index, name, button) end

api/RunMacroText.lua

@@ -1,7 +1,7 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param "text" string 
+---@param text string
----@param "button" string 
+---@param button string
 ---Runs arbitrary text as a macro
-function RunMacroText("text", "button") end
+function RunMacroText(text, button) end

api/securecall.lua

@@ -1,8 +1,8 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param function function 
+---@param func function
----@param ... list 
+---@param ... any
----@return list ... 
+---@return ... any
 ---Calls a function without tainting the execution path. Meaningless when called from outside of the secure environment. Used in Blizzard code to call functions which may be tainted or operate on potentially tainted variables. For example, consider the function CloseSpecialWindows, which iterates through the table UISpecialFrames and hides any frames named therein. Addon authors may put the names of their frames in that table to make them automatically close when the user presses the ESC key, but this taints UISpecialFrames. Were the default UI to then call CloseSpecialWindows normally, every frame in UISpecialFrames would become tainted, which could later lead to errors when handlers on those frames call protected functions. Instead, the default UI uses securecall(CloseSpecialWindows): within CloseSpecialWindows the execution path may become tainted, but afterward the environment remains secure.
-function securecall(function, ...) end
+function securecall(func, ...) end

api/select.lua

@@ -1,9 +1,8 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param index number 
+---@param index number|"#"
----@param # string 
+---@param ... any
----@param ... list 
+---@return ... any
----@return list ... 
+---Returns one or more values from a list (...) (if using index), or the number of values in a list (if using #)
----Returns one or more values from a list (...), or the number of values in a list
+function select(index, ...) end
-function select(index, #, ...) end