Skip to content

fix(docs): index templated members, which the AST walk was skipping - #213

Merged
tettou771 merged 1 commit into
mainfrom
fix/reference-template-members
Sep 1, 2026
Merged

fix(docs): index templated members, which the AST walk was skipping#213
tettou771 merged 1 commit into
mainfrom
fix/reference-template-members

Conversation

@tettou771

Copy link
Copy Markdown
Collaborator

What

docs/reference/structure.js walks a record's members looking for CXXMethodDecl. A templated member is a FunctionTemplateDecl wrapping the method, so the walk saw none of them — and every derived artifact inherited the gap.

The most visible casualty: Node's entire Mod API has never appeared in the reference.

node->addMod<DraggableMod>();      // the documented way to attach behaviour
node->getMod<LayoutMod>();
node->hasMod<TweenMod>();
node->removeMod<LayoutMod>();

Not on trussc.org, not in FOR_AI_ASSISTANT.md, despite being used throughout the examples and addons.

How

Read the wrapped decl the way the namespace-level branch already does, and flag it 'template' so tmpl is set on the signature.

Seven symbols surface:

symbol disposition
Node::addMod / getMod / hasMod / removeMod documented (public API that was missing)
FullscreenShader::setParams documented
FileWriter::operator<< exempt from the undocumented gate as an operator
Font::reresolveAtlas not API — moved to private:

Font::reresolveAtlas sat between two public: markers and was public by accident. It is a helper the option setters call so they are order-independent; nothing outside Font references it.

Member ids now carry their namespace

symbolId() did not qualify method / field. A type in a sub-namespace would be mcp::ToolBuilder while its own method was a bare ToolBuilder::arg, and generic member names like Tool::name would read as top-level ids.

This is a no-op today. No visible symbol sits in a sub-namespace, so the id set is unchanged — verified by diffing structure.js --ids before and after: the only differences are the seven additions above, and nothing was removed. It is fixed here because it belongs to the id grammar, and because the alternative is discovering it later while changing something else.

No bindings change

Every downstream consumer already filters on tmplluagen, luagen-types, emit-sketch-api, emit-sketch-reference, implicit-conv-audit. Regenerating the Lua bindings against the new data produces an identical binding set (compared as whole assignment statements, type qualification included). addons/tcxLua/src/generated/ is therefore untouched.

Verification

node docs/reference/check.js --strict
  AST symbols  : 2481
  dup          : OK
  undocumented : 0 / 2481  ✓

Built and ran the core test suite (7/7 project + 1/1 unit) after the Font change.

Two orphans (VideoWriter::lockFrame / submitFrame) appear when the check runs on Linux and not on macOS — they live inside #if TC_ASYNC_SCREEN_CAPTURE. Pre-existing on main and unrelated to this change.

FOR_AI_ASSISTANT.md was hand-edited rather than regenerated, for the same reason: regenerating it on Linux would drop those two macOS-only symbols from the index. The five added lines match what emit-forai.js renders (signature taken from the generated reference-data.json, alphabetical position preserved).

Not in this PR

The emit-web.js / emit-forai.js changes needed to display sub-namespaced symbols. They are dead code until something actually lives in a sub-namespace, so they belong with the change that puts something there — exposing mcp::, which is the follow-up.

structure.js walks a record's members looking for CXXMethodDecl, but a
templated member is a FunctionTemplateDecl wrapping the method, so it saw
none of them. Node's whole Mod API -- addMod / getMod / hasMod / removeMod,
the documented way to attach behaviour to a node -- has therefore never
appeared in the reference, on the website or in FOR_AI_ASSISTANT.md.

Read the wrapped decl the way the namespace-level branch already does and
flag it 'template', which sets tmpl on the signature. Every downstream
consumer (luagen, luagen-types, emit-sketch-*, implicit-conv-audit) already
filters on tmpl, so no binding is generated for these: regenerating the Lua
bindings against the new data produces an identical binding set.

Seven symbols surface. Five are public API and are documented here
(Node::addMod / getMod / hasMod / removeMod, FullscreenShader::setParams).
FileWriter::operator<< is exempt from the undocumented gate as an operator.
Font::reresolveAtlas is not API at all -- it sits between two `public:`
markers and was public by accident, called only by Font's own option
setters -- so it moves to `private:`.

Also qualify member ids with their namespace. A type in a sub-namespace
would otherwise be `mcp::ToolBuilder` while its own method is a bare
`ToolBuilder::arg`, and generic member names like `Tool::name` would read
as top-level ids. No visible symbol sits in a sub-namespace today, so this
is a no-op: the id set was diffed before and after, and only the seven
additions above differ.

check.js --strict: 2481 symbols, undocumented 0. (Two orphans,
VideoWriter::lockFrame / submitFrame, appear when checking on Linux and
not on macOS -- they live inside #if TC_ASYNC_SCREEN_CAPTURE. Pre-existing
and unrelated.)
@tettou771
tettou771 merged commit 05e80df into main Sep 1, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant