acdream/docs/reviews/comment-reference-inventory.md

Comment and reference inventory

Status: complete at the recorded baseline.

Classification standard

A durable source comment should make the local invariant, retail behavior, or non-obvious constraint understandable without requiring a private conversation. External provenance is useful when it points to a stable, obtainable source. Campaign chronology is useful in research/decision records but usually not as the primary explanation inside production code.

Comments will be classified as:

• Durable invariant/provenance: explains why/order/math and cites a stable retail symbol, public document, or owned design contract.
• Useful but context-dependent: technically valuable, but requires an issue, campaign, commit, or unavailable reference to understand.
• Historical residue: describes how an older implementation changed rather than what the current code guarantees.
• Diagnostic/apparatus residue: names a temporary probe, rejected attempt, manual gate, or one-off capture in maintained code.
• Misleading/stale: contradicts current code or an active authority.
• Noise: restates code, uses phase labels as structure, or preserves no decision a maintainer needs.

Initial inventory

A Roslyn trivia scan over all 1,325 owned C# files found 37,734 actual comment trivia nodes, including 9,516 XML-documentation comments. Of those comments, 2,172 contain a campaign/slice/phase/checkpoint or commit-hash reference, 1,016 contain an issue-number reference, 1,049 name an external/reference oracle, 617 contain probe/temporary/workaround/diagnostic language, 143 contain OpenGL/ImGui or GL-owner terminology, and 16 contain TODO/FIXME/HACK/XXX markers. Categories overlap and occurrence does not by itself make a comment bad; the figures identify the review surface without matching strings or identifiers.

Area	Comment trivia	Campaign/history	Issue refs	External refs	Old graphics	Probe/workaround
App	18,009	1,215	480	121	107	244
Core	8,723	399	322	452	4	224
Runtime	5,813	227	123	112	1	46
Core.Net	2,545	156	37	328	0	23
UI.Abstractions	899	69	12	11	22	18
Headless	534	42	21	13	0	29
All remaining source/tools	1,211	64	21	12	9	33

High-signal examples already queued for review include:

• src/AcDream.App/Rendering/Wb/WbDrawDispatcher.cs, whose comments mix retail symbols and durable draw invariants with issue numbers, campaign slice migrations, deleted GL-arm history, and named throwaway probes across a 3,773-line class.
• src/AcDream.Headless/Policies/HeadlessBotPolicy.cs, whose production XML documentation contains campaign contracts, temporary evidence gathering, an open issue, and disabled diagnostic behavior.
• Tool entry points that identify themselves primarily by the issue/campaign that created them, without a maintained support/archival classification.
• src/AcDream.Core.Net/WorldSession.cs contains 69 campaign-history comments and 47 external-reference comments inside a 3,754-line transport/session owner; VendorUiController.cs contains 71 campaign-history comments.
• AcDream.UI.Abstractions still documents ImGui capture and panel behavior in interfaces used by the retained client after the ImGui backend was deleted.

The exact project counts and confirmed high-risk classes above are the final inventory. It intentionally does not propose mass deletion: durable retail symbols and local invariants are valuable, while stale backend claims, personal paths, unavailable-reference paths, campaign narration, and failed temporary-cleanup markers require targeted correction.

Confirmed reference-context problems

• “holtburger” appears 163 times across 52 owned source files and 50 times across 23 test files. Twenty-three source/test files contain a literal references/holtburger/... path, but the only tracked reference root is the uninitialized references/WorldBuilder gitlink. The citations are often valuable independent corroboration, but a new maintainer cannot inspect the cited code, commit, or license from this checkout. Examples include Core/Chat/CombatChatTranslator.cs:15-16, Runtime/Chat/ChatInputParser.cs:6-7, and numerous Core.Net wire-layout comments. Stable public URL+revision or an owned evidence extract is needed; a private/missing working-copy path is not durable provenance.
• Current source comments still describe deleted behavior. Examples include UiDatElement.cs:24-29 claiming TextureCache.UploadRgba8 sets GL_REPEAT, FrameScreenshotController.cs:7-10,61,123-247 documenting a GL thread/default-framebuffer path no production caller uses, FrameProfiler.cs:11-30 retaining an ImGui timing stage, and the dead panel interfaces described in F-012. These are misleading, not merely historical.
• RenderingDiagnostics.cs and PortalVisibilityBuilder.cs contain multiple comments explicitly ordering future maintainers to strip “throwaway” or TEMP apparatus after May/June investigations that are already closed. The code remained through the Vulkan cutover, so those comments are failed cleanup markers rather than actionable ownership. F-016 records the executable debt.
• Campaign/issue references are useful as secondary provenance, but many source comments make the chronology the primary explanation (for example the long “Night-round review F14” house-marker note in MapPageController.cs:449-481). A durable local invariant and current reachability/support status should lead; campaign labels and dates belong in linked research or decision records.
• Personal-machine paths are also embedded as provenance. The literal C:\Users\erikn occurs in 146 documentation files, 43 tool files, eight production-source files, two test files, and both root instruction files. Production examples in RetailCommandHelpTable, RetailClientCommandCatalog, WeenieErrorMessages, OptionsPanelText, ClientTextRefusals, AudioSettings, ConfigOptionsPageController, and VendorUiController cite a binary in the maintainer's Downloads directory. Several comments also give a version or CodeView identity, which is the durable evidence; the personal path adds no reproducible provenance and implies access that another maintainer does not have.