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 
----@param 1  
----@param 2  
----@param 3  
----@param 4  
----@param 5  
----@param 6  
----@return 4 runeType 
----@return  1 
----@return  2 
----@return  3 
----@return  4 
+---@alias runeSlot
+---| 1 - Leftmost
+---| 2 - Second from left
+---| 3 - Fifth from left (second from right)
+---| 4 - Sixth from left (rightmost)
+---| 5 - Third from left
+---| 6 - Fourth from left
+
+---@alias runeType
+---| 1 - Blood rune
+---| 2 - Unholy rune
+---| 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 1  
----@param 2  
----@param 3  
----@param 4  
----@param 5  
----@param 6  
----@param 7  
----@return number minModifier 
+---@param school spellSchool
+---@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 
----@param 1  
----@param 2  
----@param 3  
----@param 4  
----@param 5  
----@param 6  
----@param 7  
----@return number minCrit 
+---@alias spellSchool
+---| 1 - Physical
+---| 2 - Holy
+---| 3 - Fire
+---| 4 - Nature
+---| 5 - Frost
+---| 6 - Shadow
+---| 7 - Arcane
+
+---@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 0  
----@param 1 to NUM_PET_STABLE_SLOTS  
----@return list ... 
+---@param index number
+---@return string[] foodTypes
 ---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 0  
----@param 1 to NUM_PET_STABLE_SLOTS  
----@return string icon 
----@return string name 
----@return number level 
----@return string family 
----@return string talent 
+---@param index number
+---@return string icon
+---@return string name
+---@return number level
+---@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 talentIndex number 
----@param inspect boolean 
----@param pet boolean 
----@param talentGroup nil 
----@param 1  
----@param 2  
----@param nil  
----@return string link 
+---@param tabIndex number
+---@param talentIndex number
+---@param inspect boolean
+---@param pet boolean
+---@param talentGroup talentGroup
+---@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 1  
----@param 2  
----@param 3  
----@param 4  
----@return boolean haveTotem 
----@return string name 
----@return number startTime 
----@return number duration 
----@return string icon 
+---@param slot totemSlot
+---@return boolean haveTotem
+---@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 1  
----@param 2  
----@param 3  
----@param 4  
----@return number seconds 
+---@param slot totemSlot
+---@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 
----@param 1  
----@param 2  
----@return number pvpID 
----@return string localizedName 
----@return boolean isActive 
----@return boolean canQueue 
----@return number waitTime 
----@return boolean canEnter 
+---@alias pvpMapID
+---| 1 - Wintergrasp
+---| 2 - Tol Barad
+
+---@param pvpMapID pvpMapID
+---@return number pvpID
+---@return string localizedName
+---@return boolean isActive
+---@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 
----@param 1  
----@param 2  
----@param 3  
----@param 4  
----@param 5  
----@param 6  
----@param 7  
----@param 8  
----@param 9  
----@param 10  
----@param 11  
----@param 12  
----@param 13  
----@param 15  
----@param 16  
----@param 17  
----@param enabled boolean 
+---@alias guildControlRankFlag
+---| 1 - Guildchat listen
+---| 2 - Guildchat speak
+---| 3 - Officerchat listen
+---| 4 - Officerchat speak
+---| 5 - Promote
+---| 6 - Demote
+---| 7 - Invite Member
+---| 8 - Remove Member
+---| 9 - Set MOTD
+---| 10 - Edit Public Notes
+---| 11 - View Officer Note
+---| 12 - Edit Officer Note
+---| 13 - Modify Guild Info
+---| 15 - Use guild funds for repairs
+---| 16 - Withdraw gold from the guild bank
+---| 17 - Create Guild Event
+
+---@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 
----@param 1 or LeftButton  
----@param 2 or RightButton  
----@param 3 or MiddleButton  
----@param 4 or Button4  
----@param 5 or Button5  
----@return 1nil isDown 
+---@alias mouseButton
+---| 1 or "LeftButton" - Primary mouse button
+---| 2 or "RightButton" - Secondary mouse button
+---| 3 or "MiddleButton" - Third mouse button (or clickable scroll control)
+---| 4 or "Button4" - Fourth mouse button
+---| 5 or "Button5" - Fifth mouse button
+
+---@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 
----@param searchType 2 
----@param 1  
----@param 2  
+---@alias searchType
+---| 1 - Default "top issues" search
+---| 2 - Search for specific text
+
+---@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 
----@param talentIndex number 
----@param isPet boolean 
----@param talentGroup nil 
----@param 1  
----@param 2  
----@param nil  
+---@alias talentGroup
+---| 1 - Primary Talents
+---| 2 - Secondary Talents
+---| nil - Currently active talents
+
+---@param tabIndex number
+---@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 
----@param 0  
----@param 1  
----@param 2  
+---@alias bindingSet
+---| 0 - Default key bindings
+---| 1 - Account-wide key bindings
+---| 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 
----@param 1635148593  
----@param 1768124260  
----@param 1835692129  
----@param 1836070006  
----@return boolean isSupported 
+---@alias codecID
+---| 1635148593 - H.264 - supported natively by Apple devices like the iPod, iPhone and AppleTV; best ratio quality/size but slowest to compress
+---| 1768124260 - Apple Intermediate Codec - fastest to compress, but exclusive to Mac OS X
+---| 1835692129 - Motion JPEG - faster to compress than H.264 but it will generate a bigger file
+---| 1836070006 - MPEG-4 - supported by many digital cameras and iMovie
+
+---@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 0  
----@param 1 to NUM_PET_STABLE_SLOTS  
+---@param index number #0 for active pet otherwise 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 false  
----@param true  
----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
+---@param response boolean
+---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) end

api/RollOnLoot.lua

@@ -1,11 +1,13 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param id number 
----@param rollType 3 
----@param 0  
----@param 1  
----@param 2  
----@param 3  
+---@alias rollType number
+---| 0 - Pass (declines the loot)
+---| 1 - Roll "need" (wins if highest roll)
+---| 2 - Roll "greed" (wins if highest roll and no other member rolls "need")
+---| 3 - Disenchant
+
+---@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 name string 
----@param "button" string 
+---@param index number
+---@param name 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 "button" string 
+---@param text 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 ... list 
----@return list ... 
+---@param func function
+---@param ... any
+---@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 # string 
----@param ... list 
----@return list ... 
----Returns one or more values from a list (...), or the number of values in a list
-function select(index, #, ...) end
+---@param index number|"#"
+---@param ... any
+---@return ... any
+---Returns one or more values from a list (...) (if using index), or the number of values in a list (if using #)
+function select(index, ...) end