Files
__mahjong/docs/mirror-summary.md
T
2026-10-30 15:17:24 +01:00

4.0 KiB

Mirrored source-file study documents

Use this workflow when comparing corresponding source files across platforms. The established example is docs/render-platform-comparison.html. For a single-file study, follow docs/file-summary.md instead.

Source and scope

  • Read sources from the exact requested Git revision with git show REV:path. If no revision is specified, use HEAD and record its full commit hash.
  • Discover matching relative filenames beneath the two platform directories. State which platform-only files are excluded; never invent a counterpart.
  • Produce one downloadable, self-contained HTML document in docs/, with navigation links and one section per file pair. Preserve earlier documents unless removal is requested.
  • Record both source paths and the source revision. Preserve every source line, original line number, indentation and blank line. Escape HTML characters.

Comparison layout

  • Use one table per pair with three columns: first platform's numbered source, second platform's numbered source, and explanation. Do not create separate line-by-line explanation tables or a Status column.
  • Align corresponding function starts where possible. Insert missing-line placeholders to keep later functions aligned; preserve source order and original numbers. For example, macOS renderEffect line 12 aligns with iOS line 16 at revision f0972f0d5b.
  • Within each function or intervening block, align lines sequentially unless better semantic alignment is needed. Equal line numbers need not share a row when function alignment requires padding.
  • Compare the exact source text in each aligned row, including whitespace. Fill BOTH line-number backgrounds green when they match. Fill numbers orange when they differ. A missing line is an orange-filled dash, not a plain dash. Keep code backgrounds neutral and retain syntax highlighting.
  • Include two filled statistics boxes beneath each section heading: green for matching line count and percentage, orange for mismatched count and percentage. Show the total line count as plain text alongside them.
  • Count actual lines across BOTH files, including blank lines. A matching pair contributes two matching lines; a differing pair contributes two mismatches; a platform-only line contributes one mismatch. Missing placeholders do not count. Percentages use the combined actual-line total. Recalculate after any alignment change, and explain this counting convention in the document.

Explanations

  • Explain each distinct point once across the document, at its first relevant occurrence. Leave later cells empty unless they add information.
  • Eliminate semantic repetition, not just identical sentences. Do not repeat platform/import boilerplate such as “UIKit serves iOS” for every import.
  • Explain shared behavior once. Label iOS/macOS details only when needed to distinguish behavior. Explain the reason or consequence of platform differences.
  • Avoid redundant function summaries when the individual operations already explain the same behavior. Leave blank lines and closing braces unexplained.
  • When realigning rows, anchor each platform-specific explanation to its own source line rather than to the old visual row.

Presentation and verification

  • Inline all CSS and syntax highlighting; no external fonts, scripts or requests.
  • Use <pre><code>, white-space: pre-wrap, and overflow-wrap: anywhere. Give the code columns equal width; ensure long lines remain readable without horizontal scrolling. Do not use striped row shading.
  • Verify every source line and number against the named Git revision, in order, with no omissions or duplicates. Check function anchors, placeholder fills, both matching-number fills, statistics, and explanation attachment.
  • Review explanations for repeated clauses as well as repeated sentences.
  • Inspect the rendered HTML for layout problems. Return a clickable file link; tell the user to refresh an already open document after updates.