Audit src/index/ and src/index.ts comments (#225 Phase 2)#243
Merged
Conversation
Phase 2 for #225. Twenty-three files, 222 flagged comments. src/index/ and src/index.ts now fully audited. Declaration-level rationale moved to JSDoc across the terrain viewer (tuning constants, class field docs, dispose/toggle/sample preambles), camera controller (tilt/pan/wheel constants and keyaction preamble), DTM handler orientation contract, marker sprite renderOrder rules, hover controller class and helper preambles, cursor handler field docs, drag counter, prefab tooltip handler class and anchor, prefabs handler load channels, reset display settings whitelist, marker store class, dialog file-progression indicator lookup, and other handler class preambles. In-body design decisions kept as WHY: / INVARIANT: / SAFETY: markers: - terrain-viewer: DPR cap, neutral background, light angles, LOD decision, footprint-centre shift, canvas-y inversion, dialog close single teardown, HUD focus preservation, Shift-tab semantics, rAF seed timing, radiation full-brightness (already in worker but the matching rationale on the caller side). - camera-controller: modifier deferral, far/near depth precision, Y-up mapping in pan, keyboard vs mouse zoom/tilt rates. - dtm-handler: axis mapping, edge-clamp on plane-boundary vertices, elevation-to-local-unit conversion. - marker-sprites: renderOrder ordering (flag > signs > highlight > boxes) and depthTest-off marker-through-terrain design. - hover-controller: frame-driven raycast rationale, token-guard drop. - dnd-handler: drop-consumes-dragenter counter reset INVARIANT. - prefab-tooltip-handler, prefab-highlight-handler, marker-jump: touch device pre-scroll positioning, filter-header staleness drop, mid-await hover re-check. - prefabs-handler: two-channel emit sequencing, meshSizes-independence. - reset-display-settings: dispatch-before-removeItem persistence race. - dialog-handler: first-occurrence-wins duplicate-name INVARIANT. - prefab-inspector: countsPerDifficulty non-null SAFETY. - marker-handler: Shift+Click reservation for prefab navigation. - file-handler: webkitdirectory relative-path extraction, bundled-map preprocessing note. Deleted where variable / structure / test title already conveys the intent: two `// Do nothing` no-op comments, section header labels inside EXCLUDE_PREFAB_REGEXPS, and a dialog-flow restatement. Style: single-clause sentences using because / so / since for causation, no ; / — / colon-elaboration per the #235-#236 memo. EXCLUDED_PATHS shrinks from 26 to 3.
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
1 participant
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.
Summary
Phase 2 for #225: audit all of
src/index/andsrc/index.tsin one sweep (23 files, 222 flagged comments). Drops the 23 corresponding entries fromEXCLUDED_PATHS.Coverage
Grouped by size, largest first.
src/index/terrain-viewer.ts(62) — TERRAIN_WIDTH/SEGMENTS/DECORATION_Y_TO_DTM tuning docs → JSDoc. In-bodyWHY:on renderer DPR cap, neutral background, key/ambient lights, terrain rotation, LOD-not-implemented decision, footprint-centre shift, decoration-y-inversion, box-vs-sign responsibility, dialog close single teardown, HUD focus preservation, browser Shift-tab semantics, rAF seed timing. Class field docs (#highlightedPlacement,#mapSize,#pointerDown*,compositeCanvas) → JSDoc.#updateFlag,#sampleGroundGame,#syncHighlight,#disposeTerrain,#toggleHelppreambles → JSDoc.src/index/terrain-viewer/camera-controller.ts(24) — TILT_MAX_RAD, TILT_MIN_RAD, PAN_BOOST_MULTIPLIER, WHEEL_*_PX docs → JSDoc. CameraKeyAction preamble → JSDoc. In-bodyWHY:on modifier deferral, far/near ratio for depth precision, Y-up mapping in pan, keyboard vs mouse zoom/tilt rates.src/index/dtm-handler.ts(15) —writeYorientation contract → JSDoc. Interleaved-array WHY:, axis mapping, edge-clamp, and unit-conversion rationale kept asWHY:markers. Two empty// Do nothingno-op comments deleted.src/index/terrain-viewer/marker-sprites.ts(13) — GLYPH_TEXTURE_PX, MarkerPlacement, buildSignSprites preambles → JSDoc.WHY:on renderOrder ordering (flag over signs; sprites over boxes and highlight) and depthTest-off marker-through-terrain design.anchorCenterpreamble → JSDoc.src/index/terrain-viewer/hover-controller.ts(11) — Class preamble → JSDoc.WHY:on frame-driven raycast rationale.setBoxesand#anchorpreambles → JSDoc. Controller token guard rationale →WHY:.src/index/cursor-handler.ts(11) — CursorEventMessage field docs + class preamble → JSDoc.#dispatchthrottling rationale → JSDoc on the field.src/index/dnd-handler.ts(9) — DragCounter preamble → JSDoc. Drop-consumes-dragenter reset rationale →WHY:.src/index/prefab-tooltip-handler.ts(8) — Class preamble, Shift+Click browser semantic, footprint-anchored positioning → JSDoc /WHY:.src/index.ts(8) — Shared-fetch de-duplication, restore-before-init ordering, off-DOM composite canvas, single tooltip controller rationale →WHY:.src/index/prefabs-handler.ts(7) — Two-channel emit sequencing (raw all vs hit index), meshSizes-independence rationale →WHY:. addAllPrefabsListener contract → JSDoc.src/index/prefab-highlight-handler.ts(7) — Nested-block-row closest() rationale, filter-header staleness drop, mid-await hover re-check, touch-device pre-scroll positioning →WHY:.src/index/terrain-viewer/prefab-boxes.ts(6) — BoxPlacement, mesh field, BURIED_HIGHLIGHT, buildBoxHighlight preambles → JSDoc.src/index/reset-display-settings.ts(6) — RESET_KEYS whitelist rationale → JSDoc. Dispatch-before-removeItem persistence-race rationale →WHY:.src/index/prefab-inspector-handler.ts(5) — Section header labels inside EXCLUDE_PREFAB_REGEXPS deleted (regex prefixes are self-explanatory). Non-null assertion at difficulty index →SAFETY:.src/index/marker-handler.ts(5) — Class preamble → JSDoc. Shift+Click reservation for prefab navigation →WHY:.src/index/file-handler.ts(5) — webkitdirectory relative-path extraction, bundled-map preprocessing note kept asWHY:. "Prevent opening the dialog" restatement deleted (the flow structure conveys it).src/index/dialog-handler.ts(4) —#liByNamelookup rationale → JSDoc on the field. First-occurrence-wins duplicate-name rule →INVARIANT:.src/index/marker-store.ts(3) — Class preamble → JSDoc.src/index/marker-coords-display-handler.ts(3) — Class preamble → JSDoc.src/index/cursor-coords-display-handler.ts(3) — Class preamble → JSDoc.src/index/controller-highlight.ts(3) — setHighlightFor preamble → JSDoc.src/index/marker-jump-handler.ts(2) — Touch-device pre-scroll rationale →WHY:.src/index/map-canvas-handler.ts(2) —compositeCanvasfield description → JSDoc.Style
Single-clause
WHY:/INVARIANT:/SAFETY:markers usingso/because/sincefor causation. JSDoc bodies split into short sentences with period. No;,—, or colon-elaboration in prose.Test plan
deno task ci:lintpassesdeno task ci:fmt-checkpassesdeno task ci:type-checkpassesdeno task test— 41 tests / 241 steps passProgress
EXCLUDED_PATHS: 26 → 3. Remaining:e2e/index.spec.ts,e2e/prefabs.spec.ts,playwright.config.ts(the last PR).