Files
ClassicAPI/AddOns/!!!ClassicAPI/APIDocumentation/EventsAPIMixin.lua
T
Brues 108a91a843 feat(api): describe the API in the code, browse it with /classicapi
docs/API.md is 18.7k lines and its anchors are signature slugs, so editing a
signature breaks the 281 internal and 88 README links into it. Blizzard
solved the same problem by shipping the API as data plus a browser addon,
and warcraft.wiki.gg renders those same tables. One set of descriptors can
feed all three.

Each registration now carries one next to it: typed arguments and returns,
nilability, defaults, and a sentence. Events, enumerations and returned table
shapes are described the same way. No Script_* body changed.

Game.h gains namespace Game::Doc (Field with Req/Opt/Vararg, FieldList,
Function, Method, Structure, Event) and a trailing descriptor argument on all
six Game::Lua::Register* plus Event::Custom::AutoReserve.

api/Documentation.cpp records every registration on the first pass of each
Lua state and seals it, so /reload re-registers but records nothing and the
environment comes from which pass saw the name. Export is lazy: nothing is
materialized until C_APIDocumentation.GetSystem asks for one system, because
eager export would build thousands of tables per reload for a slash command.
_classicapi_UndocumentedAPI lists what still has no descriptor.

AddOns/!!!ClassicAPI/APIDocumentation/ ports Blizzard_APIDocumentation's eight
files. Named /classicapi, not /api: the browser holds only what ClassicAPI
adds, so /api would have implied the whole 1.12 surface. Two deliberate
differences from the retail source, both noted in the file headers: a system
search also matches its namespace, since that is the name people type; and an
undocumented function says so, because an empty signature otherwise reads as
a real one.

LinkUtil gains the SetItemRef to LinkUtil.ProcessLink dispatch. That handler
registry was dead code; a new link type now registers a handler instead of
stacking another SetItemRef override. Also defines assertsafe there, which
was undefined and only mattered once the function went live.

Documented: the C_Spell and C_SpellBook surface, the spell globals, both
spellbook enumerations, the 13 UNIT_SPELLCAST_* events, GameTooltip as the
widget-method example and C_Glue as the glue and mixed-environment example.
66 of 692 function registrations. tools/New-ApiDocSkeletons.ps1 emits
paste-ready skeletons to make the rest of the sweep tractable.

Verified in game: the browser lists, searches, and prints detail; links
render and click through; right-click copies and shift-click dumps.
2026-09-12 23:20:46 -05:00

105 lines
3.0 KiB
Lua

-- Backport of Blizzard_APIDocumentation/EventsAPIMixin.lua to vanilla 1.12 /
-- Lua 5.0.
--
-- Implementation differences from the retail source:
-- - The clipboard snippet uses this client's event convention. Handlers
-- here read the `event` and `arg1`..`argN` globals rather than a vararg
-- list, so the copied body declares those instead of `local a = ...`.
EventsAPIMixin = CreateFromMixins(BaseAPIMixin);
function EventsAPIMixin:GetParentName() -- override
if self.System then
return self.System:GetName();
end
return "";
end
function EventsAPIMixin:GetType() -- override
return "event";
end
function EventsAPIMixin:GetLinkHexColor()
return "77ff22";
end
function EventsAPIMixin:GetClipboardString()
local lines = {};
table.insert(lines, ([[if event == "%s" then]]):format(self.LiteralName));
if self.Payload then
local names = {};
for i, payloadInfo in ipairs(self.Payload) do
table.insert(names, ("local %s = arg%d;"):format(payloadInfo:GetName(), i));
end
table.insert(lines, "\t" .. table.concat(names, " "));
end
table.insert(lines, "end");
return table.concat(lines, "\r\n");
end
function EventsAPIMixin:GetFullName(decorateOptionals, includeColorCodes) -- override
if self.System then
return ("Event.%s.%s -> %s"):format(self.System:GetName(), self:GetName(), self:GetPayloadString(decorateOptionals, includeColorCodes));
end
return ("Event.%s -> %s"):format(self:GetName(), self:GetPayloadString(decorateOptionals, includeColorCodes));
end
function EventsAPIMixin:MatchesSearchString(searchString) -- override
if self:GetLoweredName():match(searchString) then
return true;
end
if self.System and self.System:GetLoweredName():match(searchString) then
return true;
end
if self.LiteralName:lower():match(searchString) then
return true;
end
if self:MatchesAnyDocumentation(searchString) then
return true;
end
if self:MatchesAnyAPI(self.Payload, searchString) then
return true
end
return false;
end
function EventsAPIMixin:GetPayloadString(decorateOptionals, includeColorCodes) -- override
if self.Payload then
local values = {};
for i, payloadInfo in ipairs(self.Payload) do
if includeColorCodes ~= false then
table.insert(values, ("%s|cff%s"):format(payloadInfo:GetPayloadString(decorateOptionals, includeColorCodes), self:GetLinkHexColor()));
else
table.insert(values, payloadInfo:GetPayloadString(decorateOptionals, includeColorCodes));
end
end
return table.concat(values, ", ");
end
return "";
end
function EventsAPIMixin:GetDetailedOutputLines() -- override
local lines = {};
table.insert(lines, self:GetSingleOutputLine());
self:AddSystemTag(lines);
self:AddDocumentationTags(lines);
table.insert(lines, APIDocumentation:GetIndentString() .. "Literal Name: \"" .. self.LiteralName .. "\"");
if self.Payload then
table.insert(lines, APIDocumentation:GetIndentString() .. "Payload");
for i, payloadInfo in ipairs(self.Payload) do
table.insert(lines, APIDocumentation:GetIndentString(2) .. ("%d. %s"):format(i, payloadInfo:GetSingleOutputLine()));
end
end
return lines;
end