Files
ClassicAPI/src/api/Documentation.cpp
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

691 lines
25 KiB
C++

// This file is part of ClassicAPI.
//
// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
// of the GNU General Public License as published by the Free Software Foundation, either
// version 3 of the License, or (at your option) any later version.
//
// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
// PURPOSE. See the GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License along with
// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
// API documentation: the record of every Lua registration plus its
// descriptor, exported on demand as Blizzard `APIDocumentation` tables.
//
// C_APIDocumentation.GetSystems() -> sorted array of system Names
// C_APIDocumentation.GetSystem(name) -> one System table (Blizzard shape), or nil
// _classicapi_UndocumentedAPI() -> array of registrations lacking a
// descriptor, and its count
//
// The registrars in Game.cpp call `Record*` (see Documentation.h). Recording
// runs once per Lua state — the first in-game pass and the first glue pass —
// because the set of registrations is static: every module registers the
// same names on every `/reload`. The recorded list is never materialized
// into Lua wholesale; `GetSystem` builds ONE system's table per call, which
// is how Blizzard's browser loads too (its generated data addon is
// LoadOnDemand). Eager export would create thousands of tables on every
// `/reload` for a feature used from a slash command.
//
// System grouping is derived, never authored, except for two strings:
// - `C_Spell.X` -> System "Spell", Namespace "C_Spell" (strip `C_`)
// - `table.insert` -> System "table", Namespace "table"
// - a global -> `doc->system` ("SpellGlobals"); a global whose
// descriptor names no system has no home and is
// listed by the coverage function
// - a frame method -> Blizzard's widget system for its registry
// ("SimpleTextureAPI", Type "ScriptObject")
// - an enum / structure /
// event -> the System named in its declaration
// A system's `Environment` is "All" when its functions were recorded in both
// Lua states, else "Game" or "Glue"; a function whose own environment is
// narrower than its system's gets a Documentation line saying so.
#include "api/Documentation.h"
#include "Game.h"
#include "Offsets.h"
#include "debug/Log.h"
#include "event/Custom.h"
#include <algorithm>
#include <cctype>
#include <cstdlib>
#include <cstring>
#include <string>
#include <vector>
namespace Api::Documentation {
using Game::Doc::Field;
using Game::Doc::FieldList;
using Game::Doc::Function;
using Game::Doc::Method;
using Game::Doc::Structure;
// NOT `using Game::Doc::Event` — that name would shadow the global `Event`
// namespace for the whole file, so `Event::Custom::…` would resolve to the
// type. Same trap as `Time::Tick` vs the `Tick` namespace (see CLAUDE.md).
using EventDoc = Game::Doc::Event;
// Head of the self-registering `Structure` list. Constant-initialized, so it
// is valid before any `Structure` constructor runs, whatever the cross-TU
// static-init order.
const Structure *g_structureHead = nullptr;
namespace {
enum Kind : uint8_t {
KIND_GLOBAL, // RegisterGlobalFunction / RegisterGlueFunction / RegisterGlobalAlias
KIND_TABLE, // RegisterTableFunction
KIND_FRAME_METHOD, // RegisterFrameMethods, one per entry
KIND_ENUM, // RegisterIntegerEnum
KIND_ORPHAN_METHOD_DOC // a Doc::Method naming no entry in its table
};
struct Entry {
Kind kind;
unsigned env; // Env bits the registration was recorded in
const char *table; // KIND_TABLE: the namespace; KIND_ENUM: the parent ("Enum")
const char *name; // registered name / method name / enum sub-name
const void *registry; // frame methods only
const Function *doc; // nullptr = undocumented
const char *enumSystem;
const Game::Lua::EnumIntegerEntry *enumEntries;
int enumCount;
};
std::vector<Entry> g_entries;
Env g_pass = ENV_NONE;
unsigned g_sealed = 0;
int g_recordedThisPass = 0;
constexpr const char *kDebugPrefix = "_classicapi_";
bool IsDebugName(const char *name) {
return std::strncmp(name, kDebugPrefix, std::strlen(kDebugPrefix)) == 0;
}
bool SameText(const char *a, const char *b) {
if (a == nullptr || b == nullptr)
return a == b;
return std::strcmp(a, b) == 0;
}
bool SameTextNoCase(const char *a, const char *b) {
if (a == nullptr || b == nullptr)
return a == b;
return _stricmp(a, b) == 0;
}
Entry *Find(Kind kind, const char *table, const char *name, const void *registry) {
for (Entry &e : g_entries) {
if (e.kind == kind && e.registry == registry && SameText(e.table, table) &&
SameText(e.name, name))
return &e;
}
return nullptr;
}
void Record(Kind kind, const char *table, const char *name, const void *registry,
const Function *doc) {
if (g_pass == ENV_NONE || name == nullptr)
return;
++g_recordedThisPass;
if (Entry *e = Find(kind, table, name, registry)) {
e->env |= g_pass;
if (e->doc == nullptr)
e->doc = doc;
return;
}
Entry e{};
e.kind = kind;
e.env = g_pass;
e.table = table;
e.name = name;
e.registry = registry;
e.doc = doc;
g_entries.push_back(e);
}
// ---- System resolution ------------------------------------------------------
// Blizzard's names for the widget-method systems, keyed by the engine
// registry each `FrameMethodEntry[]` is bound to.
struct WidgetSystem {
uintptr_t registry;
const char *system;
};
const WidgetSystem kWidgetSystems[] = {
{Offsets::VAR_GAMETOOLTIP_METHOD_REGISTRY, "GameTooltipAPI"},
{Offsets::VAR_REGION_METHOD_REGISTRY, "ScriptRegionAPI"},
{Offsets::VAR_FRAME_METHOD_REGISTRY, "SimpleFrameAPI"},
{Offsets::VAR_TEXTURE_METHOD_REGISTRY, "SimpleTextureAPI"},
{Offsets::VAR_FONTSTRING_METHOD_REGISTRY, "SimpleFontStringAPI"},
{Offsets::VAR_EDITBOX_METHOD_REGISTRY, "SimpleEditBoxAPI"},
{Offsets::VAR_MODEL_METHOD_REGISTRY, "SimpleModelAPI"},
};
const char *WidgetSystemFor(const void *registry) {
for (const WidgetSystem &w : kWidgetSystems)
if (reinterpret_cast<const void *>(w.registry) == registry)
return w.system;
return nullptr;
}
// "C_Spell" -> "Spell"; anything else is its own system name.
const char *SystemNameForTable(const char *table) {
if (table[0] == 'C' && table[1] == '_' && table[2] != '\0')
return table + 2;
return table;
}
// The System an entry contributes a function to, or nullptr when it has
// none (an undocumented global, a frame method on an unmapped registry).
const char *SystemOf(const Entry &e) {
switch (e.kind) {
case KIND_TABLE:
return SystemNameForTable(e.table);
case KIND_GLOBAL:
return e.doc != nullptr ? e.doc->system : nullptr;
case KIND_FRAME_METHOD:
return WidgetSystemFor(e.registry);
case KIND_ENUM:
return e.enumSystem;
default:
return nullptr;
}
}
struct SystemInfo {
const char *name;
const char *ns; // nullptr for global and widget systems
const char *type; // "System" or "ScriptObject"
unsigned env; // Env bits; 0 when nothing recorded (structures only)
};
// Merge one entry's contribution into the system list.
void AddSystem(std::vector<SystemInfo> &systems, const char *name, const char *ns,
const char *type, unsigned env) {
if (name == nullptr)
return;
for (SystemInfo &s : systems) {
if (SameTextNoCase(s.name, name)) {
if (s.ns == nullptr)
s.ns = ns;
if (type != nullptr)
s.type = type;
s.env |= env;
return;
}
}
systems.push_back(SystemInfo{name, ns, type != nullptr ? type : "System", env});
}
std::vector<SystemInfo> CollectSystems() {
std::vector<SystemInfo> systems;
for (const Entry &e : g_entries) {
switch (e.kind) {
case KIND_TABLE:
AddSystem(systems, SystemNameForTable(e.table), e.table, "System", e.env);
break;
case KIND_GLOBAL:
AddSystem(systems, SystemOf(e), nullptr, "System", e.env);
break;
case KIND_FRAME_METHOD:
AddSystem(systems, SystemOf(e), nullptr, "ScriptObject", e.env);
break;
case KIND_ENUM:
AddSystem(systems, e.enumSystem, nullptr, nullptr, 0);
break;
default:
break;
}
}
for (const Structure *s = g_structureHead; s != nullptr; s = s->next)
AddSystem(systems, s->system, nullptr, nullptr, 0);
const int events = Event::Custom::ReservedCount();
for (int i = 0; i < events; ++i) {
const EventDoc *doc = Event::Custom::ReservedDoc(i);
if (doc != nullptr)
AddSystem(systems, doc->system, nullptr, nullptr, 0);
}
return systems;
}
const SystemInfo *FindSystem(const std::vector<SystemInfo> &systems, const char *query) {
for (const SystemInfo &s : systems)
if (SameTextNoCase(s.name, query) || SameTextNoCase(s.ns, query))
return &s;
return nullptr;
}
const char *EnvironmentName(unsigned env) {
if (env == (ENV_GAME | ENV_GLUE) || env == 0)
return "All";
return env == ENV_GLUE ? "Glue" : "Game";
}
// ---- Export builders (each leaves exactly what its comment says) -------------
namespace Lua = Game::Lua;
// Sets `Documentation = { line1 [, line2 [, line3]] }` on the table at
// stack[-1]; no-op when every line is null.
void SetDocumentation(void *L, const char *l1, const char *l2 = nullptr,
const char *l3 = nullptr) {
if (l1 == nullptr && l2 == nullptr && l3 == nullptr)
return;
Lua::PushString(L, "Documentation");
Lua::NewTable(L);
int n = 0;
for (const char *line : {l1, l2, l3}) {
if (line == nullptr)
continue;
Lua::PushNumber(L, static_cast<double>(++n));
Lua::PushString(L, line);
Lua::SetTable(L, -3);
}
Lua::SetTable(L, -3);
}
// A Lua literal from a descriptor's `defaultValue`, pushed as the value it
// denotes: `true`/`false` -> boolean, a quoted string -> string, else number.
void PushDefault(void *L, const char *literal) {
if (std::strcmp(literal, "true") == 0) {
Lua::PushBool(L, true);
} else if (std::strcmp(literal, "false") == 0) {
Lua::PushBool(L, false);
} else if (literal[0] == '"') {
const size_t len = std::strlen(literal);
Lua::PushLString(L, literal + 1, static_cast<unsigned>(len >= 2 ? len - 2 : 0));
} else {
Lua::PushNumber(L, std::strtod(literal, nullptr));
}
}
// Pushes one field record: { Name, Type, Nilable [, Default] [, Documentation] }.
void PushField(void *L, const Field &f) {
Lua::NewTable(L);
Lua::SetFieldString(L, "Name", f.name);
Lua::SetFieldString(L, "Type", f.type);
Lua::SetFieldBool(L, "Nilable", f.nilable);
if (f.defaultValue != nullptr) {
Lua::PushString(L, "Default");
PushDefault(L, f.defaultValue);
Lua::SetTable(L, -3);
}
SetDocumentation(L, f.doc);
}
// Sets `stack[-1][key] = { field records }`; no-op for an empty list.
void SetFieldArray(void *L, const char *key, FieldList list) {
if (list.count <= 0)
return;
Lua::PushString(L, key);
Lua::NewTable(L);
for (int i = 0; i < list.count; ++i) {
Lua::PushNumber(L, static_cast<double>(i + 1));
PushField(L, list.data[i]);
Lua::SetTable(L, -3);
}
Lua::SetTable(L, -3);
}
constexpr const char *kExtensionNote = "ClassicAPI extension - not part of the Blizzard API.";
constexpr const char *kGlueOnlyNote = "Available only on the glue screen.";
constexpr const char *kGameOnlyNote = "Available only in-game.";
// An undocumented function lists with no arguments, which is indistinguishable
// from a function that genuinely takes none. Say which it is, so an empty
// signature is never read as a real one.
constexpr const char *kUndocumentedNote =
"Not documented yet. Its arguments and return values are not listed here.";
// Pushes one function record. An undocumented entry still lists by name so
// `/classicapi <System> list` shows the whole surface; its shape arrives with
// the descriptor.
void PushFunction(void *L, const Entry &e, unsigned systemEnv) {
Lua::NewTable(L);
Lua::SetFieldString(L, "Name", e.name);
Lua::SetFieldString(L, "Type", "Function");
const char *envNote = nullptr;
if (e.env != systemEnv && e.env != 0)
envNote = (e.env == ENV_GLUE) ? kGlueOnlyNote : kGameOnlyNote;
if (e.doc == nullptr) {
SetDocumentation(L, kUndocumentedNote, envNote);
return;
}
SetDocumentation(L, e.doc->summary, e.doc->extension ? kExtensionNote : nullptr, envNote);
SetFieldArray(L, "Arguments", e.doc->args);
SetFieldArray(L, "Returns", e.doc->rets);
}
// Pushes { Name, Type = "Enumeration", NumValues, MinValue, MaxValue,
// Fields = { { Name, Type = <enum>, EnumValue } } }.
void PushEnumeration(void *L, const Entry &e) {
int minValue = 0, maxValue = 0;
for (int i = 0; i < e.enumCount; ++i) {
const int v = e.enumEntries[i].value;
if (i == 0 || v < minValue)
minValue = v;
if (i == 0 || v > maxValue)
maxValue = v;
}
Lua::NewTable(L);
Lua::SetFieldString(L, "Name", e.name);
Lua::SetFieldString(L, "Type", "Enumeration");
Lua::SetFieldNumber(L, "NumValues", e.enumCount);
Lua::SetFieldNumber(L, "MinValue", minValue);
Lua::SetFieldNumber(L, "MaxValue", maxValue);
Lua::PushString(L, "Fields");
Lua::NewTable(L);
for (int i = 0; i < e.enumCount; ++i) {
Lua::PushNumber(L, static_cast<double>(i + 1));
Lua::NewTable(L);
Lua::SetFieldString(L, "Name", e.enumEntries[i].key);
Lua::SetFieldString(L, "Type", e.name);
Lua::SetFieldNumber(L, "EnumValue", e.enumEntries[i].value);
Lua::SetTable(L, -3);
}
Lua::SetTable(L, -3);
}
// Pushes { Name, Type = "Structure" [, Documentation], Fields = { … } }.
void PushStructure(void *L, const Structure &s) {
Lua::NewTable(L);
Lua::SetFieldString(L, "Name", s.name);
Lua::SetFieldString(L, "Type", "Structure");
SetDocumentation(L, s.summary);
SetFieldArray(L, "Fields", s.fields);
}
// "LOSS_OF_CONTROL_ADDED" -> "LossOfControlAdded" (Blizzard's event Name).
void PascalCase(const char *literal, char *out, size_t cap) {
size_t o = 0;
bool upper = true;
for (const char *p = literal; *p != '\0' && o + 1 < cap; ++p) {
if (*p == '_') {
upper = true;
continue;
}
const unsigned char c = static_cast<unsigned char>(*p);
out[o++] = static_cast<char>(upper ? std::toupper(c) : std::tolower(c));
upper = false;
}
out[o] = '\0';
}
// Pushes { Name, Type = "Event", LiteralName [, Documentation] [, Payload] }.
void PushEvent(void *L, const char *literal, const EventDoc &doc) {
char name[128];
PascalCase(literal, name, sizeof name);
Lua::NewTable(L);
Lua::SetFieldString(L, "Name", name);
Lua::SetFieldString(L, "Type", "Event");
Lua::SetFieldString(L, "LiteralName", literal);
SetDocumentation(L, doc.summary);
SetFieldArray(L, "Payload", doc.payload);
}
// Pushes the whole System table for `sys`.
void PushSystem(void *L, const SystemInfo &sys) {
Lua::NewTable(L);
Lua::SetFieldString(L, "Name", sys.name);
Lua::SetFieldString(L, "Type", sys.type);
if (sys.ns != nullptr)
Lua::SetFieldString(L, "Namespace", sys.ns);
Lua::SetFieldString(L, "Environment", EnvironmentName(sys.env));
Lua::PushString(L, "Functions");
Lua::NewTable(L);
int n = 0;
for (const Entry &e : g_entries) {
if (e.kind != KIND_GLOBAL && e.kind != KIND_TABLE && e.kind != KIND_FRAME_METHOD)
continue;
if (!SameTextNoCase(SystemOf(e), sys.name) || IsDebugName(e.name))
continue;
Lua::PushNumber(L, static_cast<double>(++n));
PushFunction(L, e, sys.env);
Lua::SetTable(L, -3);
}
Lua::SetTable(L, -3);
Lua::PushString(L, "Events");
Lua::NewTable(L);
n = 0;
const int events = Event::Custom::ReservedCount();
for (int i = 0; i < events; ++i) {
const EventDoc *doc = Event::Custom::ReservedDoc(i);
if (doc == nullptr || !SameTextNoCase(doc->system, sys.name))
continue;
Lua::PushNumber(L, static_cast<double>(++n));
PushEvent(L, Event::Custom::ReservedName(i), *doc);
Lua::SetTable(L, -3);
}
Lua::SetTable(L, -3);
Lua::PushString(L, "Tables");
Lua::NewTable(L);
n = 0;
for (const Structure *s = g_structureHead; s != nullptr; s = s->next) {
if (!SameTextNoCase(s->system, sys.name))
continue;
Lua::PushNumber(L, static_cast<double>(++n));
PushStructure(L, *s);
Lua::SetTable(L, -3);
}
for (const Entry &e : g_entries) {
if (e.kind != KIND_ENUM || !SameTextNoCase(e.enumSystem, sys.name))
continue;
Lua::PushNumber(L, static_cast<double>(++n));
PushEnumeration(L, e);
Lua::SetTable(L, -3);
}
Lua::SetTable(L, -3);
}
// ---- Coverage ---------------------------------------------------------------
std::vector<std::string> Undocumented() {
std::vector<std::string> out;
const std::vector<SystemInfo> systems = CollectSystems();
for (const Entry &e : g_entries) {
if (IsDebugName(e.name))
continue;
switch (e.kind) {
case KIND_GLOBAL:
if (e.doc == nullptr) {
out.push_back(e.name);
} else if (e.doc->system == nullptr) {
out.push_back(std::string(e.name) + " (doc has no system)");
} else if (const SystemInfo *s = FindSystem(systems, e.doc->system);
s != nullptr && s->ns != nullptr) {
out.push_back(std::string(e.name) + " (system '" + e.doc->system +
"' is namespaced)");
}
break;
case KIND_TABLE:
if (e.doc == nullptr)
out.push_back(std::string(e.table) + "." + e.name);
break;
case KIND_FRAME_METHOD: {
const char *sys = WidgetSystemFor(e.registry);
if (sys == nullptr)
out.push_back(std::string(e.name) + " (method registry not mapped)");
else if (e.doc == nullptr)
out.push_back(std::string(sys) + ":" + e.name);
break;
}
case KIND_ORPHAN_METHOD_DOC: {
const char *sys = WidgetSystemFor(e.registry);
out.push_back(std::string(sys != nullptr ? sys : "?") + ":" + e.name +
" (doc for unregistered method)");
break;
}
case KIND_ENUM:
if (e.enumSystem == nullptr)
out.push_back(std::string(e.table) + "." + e.name);
break;
}
}
const int events = Event::Custom::ReservedCount();
for (int i = 0; i < events; ++i)
if (Event::Custom::ReservedDoc(i) == nullptr)
out.push_back(std::string("event ") + Event::Custom::ReservedName(i));
return out;
}
// ---- Lua surface ------------------------------------------------------------
int __fastcall Script_GetSystems(void *L) {
std::vector<SystemInfo> systems = CollectSystems();
std::sort(systems.begin(), systems.end(), [](const SystemInfo &a, const SystemInfo &b) {
return _stricmp(a.name, b.name) < 0;
});
Lua::NewTable(L);
for (size_t i = 0; i < systems.size(); ++i) {
Lua::PushNumber(L, static_cast<double>(i + 1));
Lua::PushString(L, systems[i].name);
Lua::SetTable(L, -3);
}
return 1;
}
int __fastcall Script_GetSystem(void *L) {
if (!Lua::IsString(L, 1)) {
Lua::Error(L, "Usage: C_APIDocumentation.GetSystem(name)");
return 0;
}
const char *query = Lua::ToString(L, 1);
const std::vector<SystemInfo> systems = CollectSystems();
const SystemInfo *sys = FindSystem(systems, query);
if (sys == nullptr)
return 0; // nil
Lua::CheckStack(L, 32);
PushSystem(L, *sys);
return 1;
}
int __fastcall Script_UndocumentedAPI(void *L) {
const std::vector<std::string> names = Undocumented();
Lua::NewTable(L);
for (size_t i = 0; i < names.size(); ++i) {
Lua::PushNumber(L, static_cast<double>(i + 1));
Lua::PushString(L, names[i].c_str());
Lua::SetTable(L, -3);
}
Lua::PushNumber(L, static_cast<double>(names.size()));
return 2;
}
const Field kGetSystemsRets[] = {
Game::Doc::Req("systems", "table", "Array of system Names, sorted without regard to case."),
};
const Function kGetSystems{
"Returns the name of every documented system.",
{}, kGetSystemsRets, nullptr, true};
const Field kGetSystemArgs[] = {
Game::Doc::Req("system", "string", "A system Name or Namespace; case does not matter."),
};
const Field kGetSystemRets[] = {
Game::Doc::Opt("system", "table", nullptr,
"The system in Blizzard's APIDocumentation table shape, or nil when unknown."),
};
const Function kGetSystem{
"Returns one system's documentation table.",
kGetSystemArgs, kGetSystemRets, nullptr, true};
void RegisterLuaFunctions() {
Game::Lua::RegisterTableFunction("C_APIDocumentation", "GetSystems", &Script_GetSystems,
&kGetSystems);
Game::Lua::RegisterTableFunction("C_APIDocumentation", "GetSystem", &Script_GetSystem,
&kGetSystem);
Game::Lua::RegisterGlobalFunction("_classicapi_UndocumentedAPI", &Script_UndocumentedAPI);
}
const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
} // namespace
// ---- Recording (called from Game.cpp) ----------------------------------------
void BeginPass(Env env) {
g_pass = (g_sealed & env) != 0 ? ENV_NONE : env;
g_recordedThisPass = 0;
}
void EndPass() {
if (g_pass == ENV_NONE)
return;
g_sealed |= g_pass;
const Env done = g_pass;
g_pass = ENV_NONE;
const std::vector<std::string> missing = Undocumented();
Debug::Log::Printf("[doc] %s pass: %d registrations recorded, %d undocumented",
done == ENV_GLUE ? "glue" : "game", g_recordedThisPass,
static_cast<int>(missing.size()));
}
void RecordGlobal(const char *name, const Function *doc) {
Record(KIND_GLOBAL, nullptr, name, nullptr, doc);
}
void RecordTable(const char *table, const char *name, const Function *doc) {
Record(KIND_TABLE, table, name, nullptr, doc);
}
void RecordFrameMethods(const void *registry, const Game::Lua::FrameMethodEntry *table,
int count, const Method *docs, int docCount) {
if (g_pass == ENV_NONE)
return;
for (int i = 0; i < count; ++i) {
const Function *doc = nullptr;
for (int d = 0; d < docCount; ++d) {
if (std::strcmp(docs[d].name, table[i].name) == 0) {
doc = docs[d].doc;
break;
}
}
Record(KIND_FRAME_METHOD, nullptr, table[i].name, registry, doc);
}
for (int d = 0; d < docCount; ++d) {
bool matched = false;
for (int i = 0; i < count && !matched; ++i)
matched = std::strcmp(docs[d].name, table[i].name) == 0;
if (!matched)
Record(KIND_ORPHAN_METHOD_DOC, nullptr, docs[d].name, registry, docs[d].doc);
}
}
void RecordEnum(const char *parent, const char *sub, const Game::Lua::EnumIntegerEntry *entries,
int count, const char *system) {
if (g_pass == ENV_NONE || sub == nullptr)
return;
++g_recordedThisPass;
if (Entry *e = Find(KIND_ENUM, parent, sub, nullptr)) {
e->env |= g_pass;
if (e->enumSystem == nullptr)
e->enumSystem = system;
return;
}
Entry e{};
e.kind = KIND_ENUM;
e.env = g_pass;
e.table = parent;
e.name = sub;
e.enumSystem = system;
e.enumEntries = entries;
e.enumCount = count;
g_entries.push_back(e);
}
} // namespace Api::Documentation
// The Structure constructor lives here so the list head is private to this
// TU; declared in Game.h beside the other descriptor types.
Game::Doc::Structure::Structure(const char *n, const char *s, FieldList f, const char *sum)
: name(n), system(s), fields(f), summary(sum), next(Api::Documentation::g_structureHead) {
Api::Documentation::g_structureHead = this;
}