docs: v1.9.0 comment-pass (Z-3) — fix false TEST-MIRROR paths, comment accuracy + density

HellionChat/CjkFallbackRange.cs

@@ -14,13 +14,8 @@ namespace HellionChat;
 // glyph-range builder (mirrors FontSizeResolver's split-for-test rationale).
 internal static class CjkFallbackRange
 {
-    // Hangul Syllables block + the FULL CJK Unified Ideographs (Han) block. The full
+    // Hangul Syllables + the full CJK Unified Ideographs (Han) block. Rationale: see
-    // Han window is REQUIRED, not optional: at UseHellionFont=true the global font is
+    // class comment. Plain start/end pairs so it stays unit-testable.
-    // Inter-Light (no CJK), so this fallback is the SOLE source for Han + Hangul. The
-    // overlap with JpRange (kanji the Japanese font also ships) is harmless under ImGui
-    // MergeMode -- the earlier-merged Japanese font wins for shared codepoints, the
-    // fallback only fills holes (简 0x7B80, 中 0x4E2D, 国 0x56FD). The dedup win is
-    // NOT re-merging the ASCII/Latin Default block, which the global font already owns.
     internal static readonly ushort[] Pairs =
     [
         0xAC00,

HellionChat/FontManager.cs

@@ -62,7 +62,7 @@ public sealed class FontManager : IDisposable
     private ushort[] JpRange = [];
 
     // B1: trimmed remainder the NotoSansCjk fallback is the sole source for
-    // (Hangul + Simplified-Han); excludes the Default/Latin block already merged
+    // (Hangul + full Han); excludes the Default/Latin block already merged
     // by the global font, so the fallback no longer re-merges the full Ranges array.
     private ushort[] CjkFallbackGlyphRange = [];
 
@@ -187,9 +187,8 @@ public sealed class FontManager : IDisposable
     // fallback is the sole Hangul/Simplified-Han source when UseHellionFont=true
     // (global=Inter-Light), so it stays in the chain — only its glyph range is
     // trimmed (CjkFallbackGlyphRange) to drop the Default-block/endonym overlap.
-    // basePt sizes the fallback to match the primary font; the Japanese merge
+    // The Japanese merge keeps its own configured size and the full JpRange (which
-    // keeps its own configured size and the full JpRange (which owns Traditional
+    // owns Traditional Han such as 體 U+9AD4), so japanese↔fallback no longer overlap.
-    // Han such as 體 U+9AD4), so japanese↔fallback no longer overlap.
     private void AddCjkAndSymbols(
         IFontAtlasBuildToolkitPreBuild tk,
         SafeFontConfig config,
@@ -200,10 +199,7 @@ public sealed class FontManager : IDisposable
         config.GlyphRanges = JpRange;
         AddFontWithFallback(tk, Plugin.Config.JapaneseFontV2.FontId, config, "japanese");
 
-        // v1.5.3: NotoSansCjk fallback covers Hangul, Simplified-Chinese-specific
+        // NotoSansCjk fallback, trimmed to CjkFallbackGlyphRange (B1). Merged last so earlier fonts win.
-        // Han (e.g. 简) and other CJK glyphs the primary (Inter Light / global font)
-        // and the FFXIV Japanese font do not ship. B1: trimmed to CjkFallbackGlyphRange
-        // so it no longer re-merges the Default block. Merged last so earlier fonts win.
         config.SizePt = basePt;
         config.GlyphRanges = CjkFallbackGlyphRange;
         AddFontWithFallback(

HellionChat/GameFunctions/Chat.cs

@@ -332,7 +332,7 @@ internal sealed unsafe class Chat : IDisposable
     }
 
     // Prefills + focuses our own input bar with a /tell command. The DI/Dalamud
-    // vorspann (Plugin.InputBar) lives here; the string assembly is BuildTellCommand.
+    // plumbing (Plugin.InputBar) lives here; the string assembly is BuildTellCommand.
     // The in-foray TellSpecial routing (SetEurekaTellChannel) is NOT this helper's
     // job — it stays at the call-site (v1.8.1 deferral).
     private void PrefillTellInput(string name, string? world)
@@ -453,11 +453,11 @@ internal sealed unsafe class Chat : IDisposable
         Func<uint, bool> validFn
     ) => RotateLinkshellIndex(currentIndex, rotate, validFn);
 
-    // Pure index-stepper (Dalamud-free): wrap (8 + i + delta) % 8 and return the
+    // Pure index-stepper (Dalamud-free): wrap (8 + currentIndex + delta) % 8 and return the
     // first index validFn accepts within 8 iterations, else null. Extracted so the
     // modulo/termination logic is unit-testable with a synthetic predicate; the
     // production caller binds validFn to InfoProxyLinkshell (in-game only).
-    // TEST-MIRROR: ../../Hellion Build test/_Helpers/RotateLinkshellIndexTests.cs
+    // TEST-MIRROR: ../../../Hellion Build test/_Helpers/RotateLinkshellIndexTests.cs
     internal static uint? RotateLinkshellIndex(
         uint currentIndex,
         RotateMode rotate,

HellionChat/SelfTests/GlobalStyleScopeAllocStep.cs

@@ -6,9 +6,7 @@ using HellionChat.Ui.StyleEngine;
 namespace HellionChat.SelfTests;
 
 // GC-reserve probe for the v1.9.0 B4a refactor: GlobalStyleScope.Push runs
-// once per draw frame, so its StackHandle must allocate nothing. Before the
+// once per draw frame, so its StackHandle must allocate nothing. This step drives a
-// counter rewrite it boxed 44 ImRaii structs + a List per frame; after, it
-// holds two ints and pushes straight onto the ImGui stack. This step drives a
 // real Push()->Dispose() cycle and asserts the per-thread allocation delta is
 // ~0 (not a non-null-handle check — feedback_hellion_chat_fontmanager_push_trap).
 // A warm-up cycle pays the one-time JIT/first-touch cost so the measured cycle

HellionChat/SelfTests/PerformanceBaselineStep.cs

@@ -17,9 +17,8 @@ internal sealed class PerformanceBaselineStep : ISelfTestStep
     // average out GC blips without making the manual step tedious.
     private const int TargetFrames = 1000;
 
-    // Quad proxy: ImGui emits 4 vertices + 6 indices per quad, so vertices/6
+    // Rough draw-call proxy: ImGui emits 6 indices per quad, so vertices/6 is an
-    // approximates the draw-quad count. NOT the real ImDrawData command count —
+    // intentional under-count of draw work, not the exact quad count (API-3).
-    // the <500/frame budget is checked approximately (API-3).
     private const int VerticesPerQuadProxy = 6;
 
     private readonly Plugin _plugin;

HellionChat/SelfTests/SelfTestReport.cs

@@ -6,12 +6,9 @@ using System.Text;
 
 namespace HellionChat.SelfTests;
 
-// Shared report sink so manual self-test steps leave a readable trace on disk,
+// Shared report sink so manual self-test steps leave a readable trace on disk. Each
-// not just a green Pass that flashes by for a single frame. Each call appends a
+// call appends a timestamped block to selftest-report.log in the plugin ConfigDirectory;
-// timestamped block to selftest-report.log in the plugin ConfigDirectory; the
+// the human reads the tail after running the self-test runner.
-// human reads the tail after running the self-test runner. Same idea as the B5
-// perf-baseline.json (durable, copy-pasteable output) but as one shared append
-// log so a full run leaves every reporting step's findings in one place.
 // Append (not atomic tmp+move) is fine: the runner is single-threaded on the
 // draw thread and a torn trailing line on a crash is acceptable for a debug log.
 internal static class SelfTestReport

HellionChat/Ui/StyleEngine/DrawListExtensions.cs

@@ -12,7 +12,6 @@ namespace HellionChat.Ui.StyleEngine;
 // ABGR before delegating to ImDrawList. Hover-sheen state lives in a small
 // static dictionary keyed by constant strings — keep keys constant and
 // scope to static UI elements so the per-key footprint stays bounded.
-// TEST-MIRROR: Util/ColourUtilTintTests.cs
 internal static class DrawListExtensions
 {
     private const float SheenDurationSeconds = 0.65f;
@@ -22,7 +21,7 @@ internal static class DrawListExtensions
     // highlight, not a saturated accent flash (effect level "subtle").
     private const float SheenTintStrength = 0.35f;
 
-    // A2 tuning knob: peak alpha at t=0, fading linearly to 0 over the sweep.
+    // Peak sheen alpha (low so the highlight stays subtle); DrawHoverSheen applies the falloff.
     private const byte SheenPeakAlpha = 0x40;
 
     private static readonly Dictionary<string, DateTime> SheenStarts = new();

HellionChat/Util/ColourUtil.cs

@@ -107,6 +107,7 @@ internal static class ColourUtil
     // a low factor nudges the sweep toward the element's accent hue without
     // going fully saturated (effect level stays "subtle"). RGB-only on
     // purpose -- DrawHoverSheen owns the alpha falloff.
+    // TEST-MIRROR: ../../../Hellion Build test/Util/ColourUtilTintTests.cs
     internal static uint LerpTowardWhite(uint abgr, float t)
     {
         t = Math.Clamp(t, 0f, 1f);