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

lua/git/sidebar.lua

@@ -19,8 +19,8 @@ local SIDEBAR_WIDTH = 50
 ---@field section string
 ---@field path string
 ---@field orig string?
----@field x string  porcelain v1 column 1 (always set; may be a literal space)
----@field y string  porcelain v1 column 2 (always set; may be a literal space)
+---@field x string  porcelain v1 column 1 (always set, may be a literal space)
+---@field y string  porcelain v1 column 2 (always set, may be a literal space)
 
 ---@class ow.Git.CommitEntry
 ---@field section string
@@ -39,7 +39,7 @@ local SIDEBAR_WIDTH = 50
 ---@field diff_right_win integer?
 ---@field user_aucmd integer?
 ---@field last_shown_key string?
----@field last_render_key string?  fingerprint of the last rendered state
+---@field last_render_key string?
 
 ---@type table<integer, ow.Git.SidebarState>
 local state = {}
@@ -47,8 +47,7 @@ local state = {}
 local group = vim.api.nvim_create_augroup("ow.git.sidebar", { clear = false })
 local ns = vim.api.nvim_create_namespace("ow.git.sidebar")
 
----Find the sidebar window in the current tabpage by filetype. Used as a
----fallback when we don't have a `SidebarState` handy (e.g. M.toggle).
+---Find the sidebar window in the current tabpage by filetype.
 ---@return integer? win
 ---@return integer? bufnr
 local function find_sidebar()
@@ -144,7 +143,7 @@ local function parse_branch_line(line)
 end
 
 ---Parse `git status --porcelain=v1 --branch` output into a (branch, groups)
----pair. `Unpushed` and `Unpulled` start empty here; ahead/behind commits are
+---pair. `Unpushed` and `Unpulled` start empty here. Ahead/behind commits are
 ---filled in by a follow-up `git log` once we know the upstream is set.
 ---@param stdout string
 ---@return ow.Git.BranchInfo, table<string, ow.Git.SidebarEntry[]>
@@ -432,7 +431,7 @@ local function refresh(bufnr, prefetched_stdout)
             return
         end
         -- Any fs-event that triggered this refresh might have changed the
-        -- worktree under the diff buffers we last opened; invalidate the
+        -- worktree under the diff buffers we last opened. Invalidate the
         -- cache so the next view_entry recomputes panes.
         s.last_shown_key = nil
         local fp = fingerprint(branch, groups)
@@ -635,10 +634,8 @@ local function entry_key(entry)
     return entry.section .. "|" .. entry.path .. "|" .. (entry.orig or "")
 end
 
----Split `target_win` and put its buffer into the new window. Matches the
----semantics of `:set_current_win(target); :rightbelow/leftabove vertical
----split` (the new window inherits the target's buffer; caller swaps it
----afterwards via `nvim_win_set_buf`).
+---Split `target_win` to the given side. The new window inherits
+---`target_win`'s buffer, which the caller swaps afterwards.
 ---@param target_win integer
 ---@param dir "left"|"right"
 ---@return integer
@@ -697,7 +694,7 @@ local function view_entry(s, entry, focus_left)
             -- Invocation window is gone (closed or in another tabpage).
             -- Open the diff pair by splitting from the sidebar. winfixwidth
             -- keeps the sidebar at 50 when there are other windows to
-            -- absorb the split; if the sidebar is the only window in the
+            -- absorb the split. If the sidebar is the only window in the
             -- tab, the split has to take from the sidebar itself, so
             -- restore the width explicitly.
             right_win = vsplit_at(sidebar_win, "right")
@@ -791,7 +788,7 @@ local function action_discard()
     end
     ---@cast entry ow.Git.FileEntry
     if entry.section == "Staged" then
-        util.warning("file has staged changes; unstage first with 'u'")
+        util.warning("file has staged changes, unstage first with 'u'")
         return
     end