Phase 8: Refactor documentation to improve clarity and navigation - #2724
Merged
andrewboudreau merged 4 commits intoSep 17, 2026
Merged
Conversation
✅ PR validation — Passednoverify: no source/build-data changes in this PR Each changed |
- Updated references to overlays and data in `src-domain-buckets.md`, `translation-unit-reconstruction-plan.md`, `tu-boundaries.md`, `tu-cpp-census-2026-08.md`, `tu-filename-reconstruction-pilot.md` to include links to their respective symbols.txt files for better navigation. - Changed fenced code language in `src-domain-buckets.md` for consistency. - Clarified under-segmentation notes and boundary definitions in `tu-boundaries.md` and `tu-cpp-census-2026-08.md`. - Enhanced the clarity of initializer assignments and profile mappings in `tu-filename-reconstruction-pilot.md`.
…`tu-reconstruction-pilot-report`
Alberto12345678999
force-pushed
the
add_ovXX_links_ph_8
branch
from
September 15, 2026 17:44
f7278eb to
e33583d
Compare
andrewboudreau
added a commit
to lunavyqo/sm64ds-decomp
that referenced
this pull request
Sep 18, 2026
Resolve notes/tu-production-enrollment.md by hand, keeping main's docs-refactor formatting from tangosdev#2724 (the ```sh fence on the mwldarm error block, the [ov010](../config/arm9/overlays/ov010/symbols.txt) links, *Abuku*, and the backticked TU names) with this branch's content inside it: LightBeam is spelled daObjC1Hikari_c in both places. No link in that file points at a src/ path this PR deletes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01G1Gdj5fTjMsW2VjRLpXxYA
andrewboudreau
added a commit
to lunavyqo/sm64ds-decomp
that referenced
this pull request
Sep 18, 2026
…lict notes Resolutions: * src/_ZN7Chuckya16CleanupResourcesEv.cpp (modify/delete) -- taken as a delete. The absorbed body in src/game/actors/d_a_holhei.cpp already calls SharedFilePtr::Release as a member (cast receiver), not the mangled _ZN13SharedFilePtr7ReleaseEv, so tangosdev#2725's landed change is carried, not reverted. * notes/tu-boundaries.md, notes/tu-reconstruction-pilot-2-report.md -- kept tangosdev#2724's links and headings around this branch's daHolhei_c naming, and repointed the Chuckya link at src/game/actors/d_a_holhei.cpp so no link names a path this promotion deletes. * config/decl-agreement-baseline.json -- regenerated rather than union-merged. 47 added entries, every one in src/game/actors/d_a_holhei.cpp; 213 removed, all from files this promotion or main's own promotions delete. The three _ZN12dEnemyBase_c20KillByInvincibleChar... rows are the same loose spelling src/func_ov062_02116010.c already banked. Two fixes the intact-TU link needed (PR validation: mwldarm "Undefined"): * func_ov002_020ada40 is not a symbol; ov002 names that address _ZN12dEnemyBase_c20KillByInvincibleCharERK10Vector3_16R6Player5Fix12IiE, which is what the legacy file declared. * data_02082128 is not a symbol; arm9 names that address IDENTITY_MATRIX4X3. config/tu_manifest.d/ov062/daHolhei_c.json: the 27 remaining tubuild CONFLICT notes were stale -- the source carries no markers. Rewritten to the "tubuild create warning (RESOLVED): CONFLICT: ..." wording tubuild emits, matching the one note already reconciled in this entry. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01G1Gdj5fTjMsW2VjRLpXxYA
andrewboudreau
added a commit
to lunavyqo/sm64ds-decomp
that referenced
this pull request
Sep 18, 2026
Two conflicts, both resolved by hand. src/game/actors/daTrs_c/_ZN7daTrs_c16CleanupResourcesEv.cpp (modify/delete): this branch deletes the one-function file because the class TU d_a_trs_cleanup_render.cpp absorbed the body; main's a0fc674 (tangosdev#2726) had converted three mangled-symbol calls in it into real member calls. Checked the absorbed copy before taking the delete: it already carries that conversion, and carries it further -- dActor_c::FindWithID(), mFoundActor->MarkForDestruction() through a typed dActor_c * member instead of an fBase_c cast, and an unqualified UnloadCapModel() inherited from dCapEnemy_c instead of a dCapEnemy_c cast. Nothing from tangosdev#2726 is reverted, so the file is taken as deleted. notes/tu-filename-reconstruction-pilot.md (content): main's 0fb9ed8 (tangosdev#2724) link-ified the pilot tables; this branch repointed the TERESA and BOSS_TERESA rows at d_a_trs_factories.cpp. Kept main's links and headings with this branch's targets. Main's spelling of those two rows links at d_a_trs_teresa.cpp and d_a_trs_boss_teresa.cpp, which this promotion deletes -- taking it wholesale fails check_dead_references.py on the repo-rooted path inside the link text (verified by probe). config/decl-agreement-baseline.json auto-merged without a swap: a regenerated baseline is a strict subset of the merged one (+0 entries), so nothing phantom was invented and nothing was laundered. The 28 entries added against main are the func_ov063_021166ac.cpp move, the CleanupResources absorption, and the plurality flips that follow from this branch retiring the Player::ShowMessage and dCapEnemy_c mangled externs. The 97 now-stale banked rows are left alone: the gate is a ratchet, not a cleanup, and reports them as "not a failure". config/converted-baseline.json: 2813 entries, count field agrees, set unique and sorted; the only change is OnPendingDestroy moving to the "#" form inside the class TU. Validation on the merged tree: rombuild.py -j16 --no-rom, cold cache: 8752 enrolled, 0 reused, 8752 compiled; 11,206 source-built functions reproducing, 0 mismatching; module fidelity 106/106 exact, 100.000000%; ROM-build analysis PASS check_decl_agreement.py: no new declaration disagreements check_dead_references.py: no new dead references, no broken links check_src_tu.py: every reference resolves check_tubuild_conflicts.py --list: every recorded conflict matches Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01G1Gdj5fTjMsW2VjRLpXxYA
andrewboudreau
added a commit
to lunavyqo/sm64ds-decomp
that referenced
this pull request
Sep 18, 2026
…` and `refs` Merges origin/main (c67ec9f) into the PR head. Five notes conflicted against tangosdev#2724's docs refactor, which turned bare code references into markdown links. Each is resolved by hand keeping BOTH sides: main's link formatting and fences, this branch's daObjKm2_Ami_Bou_c content inside them. notes/tu-cpp-census-2026-08.md [ov002](...) link + the new class name notes/tu-naming-and-swallowers.md three [ov045]/[ov002] links + new names notes/tu-promotion-conventions.md main's ```cpp fence + ~daObjKm2_Ami_Bou_c() notes/tu-reconstruction-pilot-2-report.md [ov045]/[ov002] links + new names notes/tu-reconstruction-pilot-report.md all five hunks, same rule tu-promotion-conventions.md keeps sections 1..6 at the same numbers on both sides, so the "section 2" citation in notes/agents/handoffs/issue-2412-daGmch_c.md still points where it did. Dead references. This promotion deletes the seven one-function sources the pilot report cites, and the branch had renamed those citations to a `legacy/` prefix. `legacy` is not a top-level directory of this repo, so the dead-reference scan cannot see those tokens at all: that hides the citation rather than fixing it. The report's baseline-control transcript now names the seven by SYMBOL and says once, in prose, that the promotion folded them into src/game/actors/d_a_obj_km2_ami_bou.cpp -- with the `src/` prefix intact, so the gate can check it. The two prose sentences that named `legacy/...cpp` name the symbol instead. config/dead-reference-baseline.json drops its now-orphaned `src/daObjKm2_Ami_Bou_c_Spawn.c` row: nothing cites that path any more. `declarations`. The new TU gives three overlay data handles real types (`SharedFilePtr` x2, `CLPS_Block`) where include/decl_common.h has the generic `int []`, which is the same shape 245 `return:SharedFilePtr` and 14 `return:CLPS_Block` rows already bank -- src/game/actors/daObjPathLift_c.cpp carries the identical `data_ov002_0210d7d4` entry. The three are banked here. Regenerating the baseline wholesale would ALSO drop 98 rows that went stale on main in files this PR never touches, so this is a surgical add instead: measured +3 / -4, the four removals being the rows the branch had keyed on src/_ZN18daObjKm2_Ami_Bou_c13InitResourcesEv.cpp, a path that has never existed. `refs`. tools/test_check_src_tu.py's forgiveness fixture was built on `PoleLift`, whose four tokens stopped resolving when this PR retired the coined name. Repointed at live names, and split across two classes on purpose: a token that IS in a symbols.txt short-circuits before the forgiveness rule and tests nothing, so the D2 comes from daObjKm2_Ami_Bou_c (ov045 licenses D1/D0 but no D2) and the _ZTV/_ZTI/_ZTS trio from fLiNdBa_c, which has no RTTI row anywhere. That is strictly more coverage than the fixture had before. Validation on the merged tree: rombuild.py -j16 --no-rom 805 compiled of 8749 enrolled; 11,206 source-built functions reproducing, 0 mismatching; module fidelity 106/106 exact, 100.000000%; ROM-build analysis PASS check_dead_references.py no new dead references, no broken markdown links check_decl_agreement.py no new declaration disagreements check_src_tu.py every reference resolves (30 TUs, 781 refs) check_tubuild_conflicts.py 178 entries, every recorded conflict matches Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01G1Gdj5fTjMsW2VjRLpXxYA
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Enhance latter half of documentation by adding overlay and data links for better navigation and updating references matching current state of project.
The
ov0xxphase is almost concluded, then, will move toov1xxphase, and whatever remainingarm9links. After that, comes another fenced code pass, before updating all other source files and docs's links.