[stacked] Final docs and architecture review #162

New issue

Closed

opened 2026-09-21 18:12:38 +00:00 by barrettruth · 0 comments

barrettruth commented

2026-09-21 18:12:38 +00:00

Owner

Original issue: barrettruth/diffs.nvim#369
Original author: barrettruth
Original date: 2026-05-28T03:27:15Z

Part of #358.

Goal

Perform a final holistic review of stacked layout before closing the tracker, after the implementation, docs, and verification issues have landed.

This is a review/refinement issue, not a feature expansion issue.

Scope

Re-read the final vimdoc for ++layout=stacked and confirm the public wording is accurate, concise, and consistent with existing help style.
Specifically review the helpdoc phrasing for:
- :Gdiff and :Greview signatures and parameter descriptions;
- side-aware line-number semantics;
- the ASCII example around replacements;
- highlight group wording for dual and single rails.
Review the final code shape across the stacked-layout PR series for small architecture cleanups that are easier to see after the full feature exists.
Look for unnecessary duplication, awkward naming, over-scoped helpers, missing ownership boundaries, or stale comments/types introduced during the series.
Confirm the final implementation still matches #358’s accepted non-goals: no public config, no split-layout behavior changes, and no rewrite of generated hunk metadata.

Non-goals

Do not add new stacked-layout behavior unless it is needed to fix a bug found during review.
Do not rename public user-facing options after docs have landed unless the tracker owner explicitly approves it.
Do not perform broad unrelated refactors.

Acceptance criteria

Helpdoc language is reviewed and adjusted if necessary.
Any small stacked-layout code cleanups are made, or explicitly deemed unnecessary.
The final code and docs still align with #358’s accepted decisions.
The root tracker can be closed after this issue and the final verification issue are complete.

> Original issue: barrettruth/diffs.nvim#369 > Original author: `barrettruth` > Original date: 2026-05-28T03:27:15Z Part of #358. ## Goal Perform a final holistic review of stacked layout before closing the tracker, after the implementation, docs, and verification issues have landed. This is a review/refinement issue, not a feature expansion issue. ## Scope - Re-read the final vimdoc for `++layout=stacked` and confirm the public wording is accurate, concise, and consistent with existing help style. - Specifically review the helpdoc phrasing for: - `:Gdiff` and `:Greview` signatures and parameter descriptions; - side-aware line-number semantics; - the ASCII example around replacements; - highlight group wording for dual and single rails. - Review the final code shape across the stacked-layout PR series for small architecture cleanups that are easier to see after the full feature exists. - Look for unnecessary duplication, awkward naming, over-scoped helpers, missing ownership boundaries, or stale comments/types introduced during the series. - Confirm the final implementation still matches #358’s accepted non-goals: no public config, no split-layout behavior changes, and no rewrite of generated hunk metadata. ## Non-goals - Do not add new stacked-layout behavior unless it is needed to fix a bug found during review. - Do not rename public user-facing options after docs have landed unless the tracker owner explicitly approves it. - Do not perform broad unrelated refactors. ## Acceptance criteria - Helpdoc language is reviewed and adjusted if necessary. - Any small stacked-layout code cleanups are made, or explicitly deemed unnecessary. - The final code and docs still align with #358’s accepted decisions. - The root tracker can be closed after this issue and the final verification issue are complete.

barrettruth

2026-09-21 18:12:38 +00:00