Comments in benilla-ui: one line of fact each, no history, no record numbers (#143)
Part of #41: the comments of `benilla-ui` (the Lua UI engine, its FrameXML loader and its widgets) are rewritten to the rule in `docs/METHOD.md`, which is what the code does and the reference fact behind it, in a line. 43,140 comment lines become 15,161. - **The mechanical strip.** The citations that were only a private record number go first, and each edit is shown to be a pure removal. - **Wrong facts corrected.** The rewrite corrects the comments that stated wrong facts. Among them: - `0x64a480` is the case-sensitive compare (a byte `repz cmpsb`), and `0x64a4c0` the case-insensitive one. - A frame's id sits at `+0xb0`, not `+0xb4`. `EnableKeyboard`/`IsKeyboardEnabled` are `0x776ec0`/`0x776f90`. - A region's unpinned edge has no fallback to its owner's rect: the owner supplies only the scale. - `$parent` expands to the nearest named ancestor, or "Top" when none is named (`0x76c5b0`), not simply to the parent. - A StatusBar fills from its internal normalised fraction, not from `GetValue()`. - The addresses of `StartDuel` and `StartDuelUnit` were swapped. - Many "untraced" notes now give the traced reference fact: the drag threshold, the per-grip sizing edges, the empty-`autoFocus` skip, and `SetTexCoordModifiesRect`'s default. - Stock FrameXML line citations are checked against the stock 1.12 files and corrected. `ref-` file names become the stock file names. - **Deviation labels.** "Deviation:" now marks only a choice with a reason. A surface that exists only for the retired Era addon target says so plainly: it is not 1.12. - **Verification.** Every file strips to identical code, and `cargo fmt --check` is clean. Nine second readers compared every file old against new, restored the facts the rewrite had dropped, and checked each new citation against the code, the stock files, vmangos and the reference. Behaviour differences the rewrite surfaced are filed as their own issues (#131–#142), and more are being validated. The comments here state what the code does. String literals are untouched; they are #92. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Sam Sung
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
8505187668
commit
fd386e75ae
@@ -1,36 +1,16 @@
|
||||
//! **benilla's widget METHOD surface, asked of a running VM** — the shared measurement behind
|
||||
//! the `dump_widget_methods` example and the widget-surface gate
|
||||
//! (`script::tests::widget_surface`, decision 2142).
|
||||
//!
|
||||
//! It exists for the same reason `dump_globals` does (decisions 1188, 1189): **it is a run, not a
|
||||
//! grep**. `_G` is not the whole surface an addon can tell apart — most of what an addon touches
|
||||
//! is reached through a *widget*, and an addon's test for "does this client have X" is
|
||||
//! `if frame.SetBackdrop then`, i.e. what the `__index` chain answers on a live instance. A regex
|
||||
//! over `m.set("Name", …)` cannot answer that: it cannot see which registry table a kind actually
|
||||
//! chains to, it cannot see the Texture/FontString leaf split ([`super::region`]), and it reads a
|
||||
//! name registered under a `format!` family as one method.
|
||||
//!
|
||||
//! So every row is one live object being asked `type(obj.Name) == "function"`, exactly as an addon
|
||||
//! asks it. The only thing **not** asked of the VM is the *candidate name list* — a metatable whose
|
||||
//! `__index` is a Rust dispatcher is not enumerable from Lua, so the candidates are the union of
|
||||
//! the keys of the VM's own method tables ([`METHOD_TABLES`]), read out of the Lua registry at
|
||||
//! runtime rather than out of the source. A key that no longer resolves to a table is a hard error
|
||||
//! rather than a silent loss of candidates: a quietly-missing candidate source would under-report
|
||||
//! the surface, which is the exact failure this measurement exists to prevent.
|
||||
//! benilla's widget method surface asked of a running VM, shared by the `dump_widget_methods`
|
||||
//! example and the widget-surface gate (`script::tests::widget_surface`). Each row is a live
|
||||
//! instance asked `type(obj.Name) == "function"`, as an addon asks it; only the candidate names
|
||||
//! come from elsewhere, the keys of the VM's method tables ([`METHOD_TABLES`]), since a Rust
|
||||
//! `__index` dispatcher cannot be enumerated from Lua.
|
||||
use std::collections::BTreeSet;
|
||||
|
||||
use mlua::{Table, Value};
|
||||
|
||||
use super::UiScript;
|
||||
|
||||
/// The named-registry method tables the VM installs — the **candidate name source**, read from the
|
||||
/// live registry.
|
||||
///
|
||||
/// This is not the class chain (the chain is `object::kind_method_registries`' business and this
|
||||
/// instrument deliberately does not model it — it asks the instance instead). It is only the
|
||||
/// universe of names worth probing: every name benilla registers on any widget appears as a key in
|
||||
/// one of these, so the union is a superset of our surface and the per-instance probe decides
|
||||
/// membership.
|
||||
/// The VM's named-registry method tables: every widget method benilla registers is a key in one,
|
||||
/// and the per-instance probe decides which a class answers.
|
||||
const METHOD_TABLES: &[&str] = &[
|
||||
"__benilla_frame_methods",
|
||||
"__benilla_region_methods",
|
||||
@@ -57,14 +37,9 @@ const METHOD_TABLES: &[&str] = &[
|
||||
"__benilla_tooltip_methods",
|
||||
];
|
||||
|
||||
/// Every widget/region/font class benilla can hand an addon, and one Lua expression that makes one.
|
||||
///
|
||||
/// **Ordered, and the order is load-bearing**: the region and font rows are made *by* the plain
|
||||
/// frame the first row creates, so `Frame` comes first. Each instance is published as the global
|
||||
/// `DW_<Class>`; the frame kinds also publish their own `CreateFrame` name, which is harmless.
|
||||
///
|
||||
/// `TaxiRouteFrame` is absent on purpose — it is a registered `CreateFrame` type that *is* a
|
||||
/// `Frame` and nothing else (decision 1828), so it would be the `Frame` row twice.
|
||||
/// Every class benilla can hand an addon, with a Lua expression making one, published as
|
||||
/// `DW_<Class>`. `Frame` must come first: the region and font rows are made by it.
|
||||
/// `TaxiRouteFrame` is left out, being a plain `Frame` to Lua.
|
||||
const CLASSES: &[(&str, &str)] = &[
|
||||
("Frame", r#"CreateFrame("Frame", "DWFrameN", UIParent)"#),
|
||||
(
|
||||
@@ -137,12 +112,8 @@ const CLASSES: &[(&str, &str)] = &[
|
||||
("Font", r#"CreateFont("DWFontN")"#),
|
||||
];
|
||||
|
||||
/// Every `(class, method)` pair this VM answers — one live instance per class, probed with the
|
||||
/// membership test an addon writes.
|
||||
///
|
||||
/// **A class that cannot be instantiated is REPORTED, never skipped**: its row is
|
||||
/// `(class, "!NOT-INSTANTIABLE")`. A census that silently drops a class reads as "that class has
|
||||
/// no methods", which is the wrong answer to a different question.
|
||||
/// Every `(class, method)` pair this VM answers, one live instance per class. A class that cannot
|
||||
/// be made reports `(class, "!NOT-INSTANTIABLE")` rather than dropping out.
|
||||
pub fn widget_method_census(script: &UiScript) -> mlua::Result<Vec<(String, String)>> {
|
||||
let mut candidates: BTreeSet<String> = BTreeSet::new();
|
||||
for key in METHOD_TABLES {
|
||||
|
||||
Reference in New Issue
Block a user