docs(git): trim verbose comments and fix prose-rule violations

lua/git/diff.lua

@@ -21,8 +21,8 @@ end
 ---The command path runs Vim's full `diff_win_options` setup, which sets
 ---an internal flag that prevents subsequently-created floats from
 ---inheriting `'diff' = 1` when opened from a focused diff pane. The raw
----option setter skips that setup, so floats (oil, fzf-lua, etc) end up
----joining the tabpage's diff group and corrupting its render.
+---option setter skips that setup, so floats end up joining the
+---tabpage's diff group and corrupting its render.
 ---@param win integer
 ---@param enabled boolean
 local function set_diff(win, enabled)
@@ -32,19 +32,15 @@ local function set_diff(win, enabled)
 end
 
 ---Render two buffers as a diff pair. The right buffer takes the current
----window; the left opens in a leftabove split (vertical or horizontal
----per `vertical`). Both windows enter Vim's diff mode via `:diffsplit`'s
----built-in setup. Drops a `'` jumplist mark before reassigning the
----current window.
+---window. The left opens in a leftabove split (vertical or horizontal
+---per `vertical`). Drops a `'` jumplist mark first so `''` jumps back.
 ---@param left integer
 ---@param right integer
 ---@param vertical boolean
 function M.open(left, right, vertical)
-    -- Read the name first: if `left` is the current window's buffer
-    -- and has `bufhidden=wipe` (a freshly-loaded `git://` URI), the
-    -- `nvim_set_current_buf(right)` below wipes it, and a later name
-    -- lookup would fail. `:diffsplit` re-bufadds + reloads from the
-    -- name, so the wipe-then-recreate sequence is fine.
+    -- Read the name first: an empty placeholder has `bufhidden=wipe`,
+    -- so `nvim_set_current_buf(right)` below wipes `left` before a
+    -- name lookup could see it. `:diffsplit` re-creates from the name.
     local left_name = vim.api.nvim_buf_get_name(left)
     vim.cmd.normal({ "m'", bang = true })
     vim.api.nvim_set_current_buf(right)
@@ -57,9 +53,8 @@ end
 ---group and re-establishes a fresh one. `nvim_win_set_buf` swaps the
 ---buffer pointer without invalidating cached diff state, and
 ---`:diffupdate` alone doesn't reliably force a recompute when no buffer
----contents have actually changed. Sides with `name` set get renamed +
----filetype-refreshed (used to relabel a fresh `empty_buf` placeholder
----as `[absent] <abs>`, or to re-run ft detection on a `git://` buffer).
+---contents have actually changed. Sides with `name` set are renamed
+---and re-run filetype detection.
 ---@param left_win integer
 ---@param right_win integer
 ---@param pair ow.Git.DiffPair
@@ -77,10 +72,8 @@ function M.update_pair(left_win, right_win, pair)
     set_diff(right_win, true)
 end
 
----Open two buffers as a diff. `a_left` decides which one goes in the
----leftabove slot (where `M.open` parks the cursor). Caller picks per
----its own rule (writable-on-left for routine flows, anchor-on-left
----when neither side is writable, etc).
+---Open two buffers as a diff. `a_left` puts `buf_a` in the leftabove
+---slot (where `M.open` parks the cursor).
 ---@param buf_a integer
 ---@param buf_b integer
 ---@param a_left boolean
@@ -94,19 +87,18 @@ local function place_pair(buf_a, buf_b, a_left, vertical)
 end
 
 ---Dispatch for `M.split` when the current buffer is a `git://<revspec>`
----URI. Placement is "writable on the left" via `place_pair`.
+---URI. Placement is writable-on-the-left via `place_pair`.
 ---
 ---gd/gh: pair cur with the worktree file at the URI's path.
 ---
----gD/gH: pair cur with the next layer toward HEAD —
+---gD/gH: pair cur with the next layer toward HEAD.
 ---  * stage 0 -> `HEAD:<p>`
 ---  * stage 2 (ours) <-> stage 3 (theirs)
----  * stage 1 (base) -> bail; ambiguous (suggest `:Gdiffsplit <ref>`)
+---  * stage 1 (base) -> bail (ambiguous, suggest `:Gdiffsplit <ref>`)
 ---  * any other ref -> `:0:<p>`
 ---
----A `<ref>` containing `:` (from `:Gdiffsplit`) short-circuits all the
----above and pairs cur with that revspec literally. This is the escape
----hatch the merge-base warning points at.
+---A `<ref>` containing `:` (from `:Gdiffsplit`) short-circuits the
+---above and pairs cur with that revspec literally.
 ---@param opts ow.Git.SplitOpts
 ---@param cur_buf integer
 ---@param cur_revspec string
@@ -119,11 +111,10 @@ local function uri_split(opts, cur_buf, cur_revspec)
     end
     local cur = util.parse_revspec(cur_revspec)
     if not cur.path then
-        util.warning("git URI has no path; cannot diff against worktree")
+        util.warning("git URI has no path, cannot diff against worktree")
         return
     end
-    -- `git.object` is lazy-required to break the load-time cycle.
-    -- It requires `git.diff` itself for `empty_buf`.
+    -- Lazy-required to break the load-time cycle with `git.object`.
     local object = require("git.object")
     local cur_writable = cur.stage == 0
 
@@ -153,7 +144,7 @@ local function uri_split(opts, cur_buf, cur_revspec)
     end
 
     if cur.stage == 1 then
-        util.warning("gD on merge base is ambiguous; use :Gdiffsplit <ref>")
+        util.warning("gD on merge base is ambiguous, use :Gdiffsplit <ref>")
         return
     end
 
@@ -184,7 +175,7 @@ local function uri_split(opts, cur_buf, cur_revspec)
 end
 
 ---@class ow.Git.SplitOpts
----@field revspec string '' for the smart-default routing (index vs worktree); a plain ref like `'HEAD'` to compare `<ref>:<rel>` against the current path; or a full revspec containing `:` (e.g. `':2:foo'`, `'HEAD~1:other.lua'`) used as-is.
+---@field revspec string `''` for smart-default routing (index vs worktree). A plain ref like `'HEAD'` compares `<ref>:<rel>` against the current path. A full revspec containing `:` (e.g. `':2:foo'`, `'HEAD~1:other.lua'`) is used as-is.
 ---@field vertical boolean
 
 ---@param opts ow.Git.SplitOpts
@@ -216,9 +207,6 @@ function M.split(opts)
         return
     end
 
-    -- A `<revspec>` containing `:` is treated as a full revspec;
-    -- otherwise the worktree-relative path is appended (the common
-    -- keymap form).
     local revspec
     if opts.revspec == "" then
         revspec = ":0:" .. rel