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

2026-06-16 20:59:09 +02:00
parent 618e029ff4
commit de9d11ba4a
8 changed files with 17 additions and 32 deletions
@@ -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
-    // Han window is REQUIRED, not optional: at UseHellionFont=true the global font is
-    // 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.
+    // Hangul Syllables + the full CJK Unified Ideographs (Han) block. Rationale: see
+    // class comment. Plain start/end pairs so it stays unit-testable.
    internal static readonly ushort[] Pairs =
    [
        0xAC00,
@@ -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
-    // keeps its own configured size and the full JpRange (which owns Traditional
-    // Han such as 體 U+9AD4), so japanese↔fallback no longer overlap.
+    // The Japanese merge keeps its own configured size and the full JpRange (which
+    // owns Traditional 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
-        // 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.
+        // NotoSansCjk fallback, trimmed to CjkFallbackGlyphRange (B1). Merged last so earlier fonts win.
        config.SizePt = basePt;
        config.GlyphRanges = CjkFallbackGlyphRange;
        AddFontWithFallback(
@@ -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,
@@ -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
-// 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
+// once per draw frame, so its StackHandle must allocate nothing. 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
@@ -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
-    // approximates the draw-quad count. NOT the real ImDrawData command count —
-    // the <500/frame budget is checked approximately (API-3).
+    // Rough draw-call proxy: ImGui emits 6 indices per quad, so vertices/6 is an
+    // intentional under-count of draw work, not the exact quad count (API-3).
    private const int VerticesPerQuadProxy = 6;

    private readonly Plugin _plugin;
@@ -6,12 +6,9 @@ using System.Text;

 namespace HellionChat.SelfTests;

-// Shared report sink so manual self-test steps leave a readable trace on disk,
-// not just a green Pass that flashes by for a single frame. Each call appends a
-// timestamped block to selftest-report.log in the plugin ConfigDirectory; the
-// 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.
+// Shared report sink so manual self-test steps leave a readable trace on disk. Each
+// call appends a timestamped block to selftest-report.log in the plugin ConfigDirectory;
+// the human reads the tail after running the self-test runner.
 // 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
@@ -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();
@@ -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);