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

lua/git/object.lua

@@ -48,7 +48,7 @@ local function diff_section()
     end
 
     -- Header lines (mode/index/oldfile/newfile/etc) sit between the
-    -- `diff --git` line and the first `@@` hunk; cap the read at 20 to
+    -- `diff --git` line and the first `@@` hunk. Cap the read at 20 to
     -- bound work even for unusual diff headers.
     local header =
         vim.api.nvim_buf_get_lines(0, diff_lnum, diff_lnum + 20, false)
@@ -135,18 +135,12 @@ local function attach_index_writer(buf, worktree, path)
     })
 end
 
----Pre-fetched content keyed by bufnr. Set by `buf_for(_, _, content)`
----and consumed by the next `read_uri` dispatch on that buffer. Lets
----callers fold validation + content fetch + buffer load into one
----`cat-file` call instead of preflighting separately.
+---Pre-fetched content keyed by bufnr, consumed once by `read_uri`.
 ---@type table<integer, string>
 local pending_content = {}
 
----Return a buffer holding the content addressed by a git revspec. The
----URI is `git://<revspec>` and BufReadCmd routes through `M.read_uri`,
----which loads via `git cat-file -p`. If `content` is given, primes a
----cache so the BufReadCmd handler reuses it instead of running another
----`cat-file -p`.
+---Return a `git://<revspec>` URI buffer. Pass `content` to prime
+---`read_uri`'s cache and skip its `cat-file -p` fetch.
 ---@param worktree string
 ---@param revspec string  any revspec git understands (e.g. `HEAD:foo`, `:foo`, `:1:foo`, `<sha>`, `<sha>:foo`)
 ---@param content string?
@@ -161,11 +155,10 @@ function M.buf_for(worktree, revspec, content)
     return buf
 end
 
----BufReadCmd handler for `git://<revspec>` URIs. Loads content via
----`git cat-file -p <revspec>`. Worktree comes from `vim.b[buf]
----.git_worktree` if set, else from cwd. Stage-0 index entries (revspec
----form `:<path>`) are made writable via `attach_index_writer` so `:w`
----updates the index. Other revspecs are read-only.
+---BufReadCmd handler for `git://<revspec>` URIs. Worktree comes from
+---`b:git_worktree` if set, else from cwd. Stage-0 index entries
+---(`:<path>`) are made writable so `:w` updates the index. Other
+---revspecs are read-only.
 ---@param buf integer
 function M.read_uri(buf)
     local name = vim.api.nvim_buf_get_name(buf)
@@ -202,9 +195,9 @@ function M.read_uri(buf)
 
     -- Bare-ref objects that dereference to a commit (commits, stashes,
     -- annotated tags pointing at a commit, lightweight tags) get their
-    -- `diff-tree -p` patch appended so the buffer is navigable: the
+    -- `diff-tree -p` patch appended so the buffer is navigable. The
     -- `<CR>` parser walks `diff --git` blocks. `^{commit}` is git's
-    -- standard "deref to commit" suffix; rev-parse fails for non-commit
+    -- standard "deref to commit" suffix. rev-parse fails for non-commit
     -- objects (trees, blobs, tags pointing at non-commits) so they
     -- naturally skip the append. `-m --first-parent` collapses merges
     -- and stashes into one diff per file (vs `diff --cc` combined
@@ -238,8 +231,7 @@ function M.read_uri(buf)
         vim.api.nvim_buf_set_lines(buf, 0, -1, false, util.split_lines(stdout))
     end
 
-    -- `b:git_ref` anchors `<CR>`-driven navigation in this buffer. Set
-    -- here once per load instead of having every caller do it.
+    -- `b:git_ref` anchors `<CR>`-driven navigation in this buffer.
     local ref_sha = repo.rev_parse(worktree, revspec, true)
     if ref_sha then
         vim.b[buf].git_ref = ref_sha
@@ -278,8 +270,8 @@ function M.read_uri(buf)
 
     -- BufReadCmd suppresses the normal BufReadPost dispatch, so
     -- modeline parsing doesn't run unless we fire it ourselves. The
-    -- modeline can still override the filetype set above; standard Vim
-    -- precedence.
+    -- modeline can still override the filetype set above (standard Vim
+    -- precedence).
     vim.api.nvim_exec_autocmds("BufReadPost", { buffer = buf })
 end
 
@@ -312,7 +304,7 @@ end
 ---@param section ow.Git.DiffSection
 local function open_section(ctx, section)
     if not section.pre_blob or not section.post_blob then
-        util.warning("no index line; cannot determine blob SHAs")
+        util.warning("no index line, cannot determine blob SHAs")
         return
     end
     local parent = ctx.parent_ref or "0"
@@ -330,13 +322,8 @@ end
 ---@field split (false|"above"|"below"|"left"|"right")?  forwarded to `util.place_buf`. Default opens a new horizontal split.
 
 ---Open any git object. Accepts a bare ref (commit / tree / blob / tag
----sha, branch, tag name, `stash@{N}`, etc.) or `<commit-ref>:<path>`
----form. Resolves the revspec to a sha so the URI stays stable if the
----ref later moves, primes the `read_uri` cache with the `cat-file -p`
----output (one subprocess instead of two — preflight + load), then goes
----through the unified URI pipeline. `read_uri` then appends the
----`diff-tree -p` patch for any revspec that dereferences to a commit
----(commits, stashes, annotated tags pointing at commits).
+---sha, branch, tag name, `stash@{N}`, etc.) or `<commit-ref>:<path>`.
+---Resolves to a sha so the URI stays stable if the ref later moves.
 ---@param worktree string
 ---@param ref string
 ---@param opts ow.Git.OpenObjectOpts?
@@ -370,9 +357,6 @@ function M.open_under_cursor()
 
     local line = vim.api.nvim_get_current_line()
 
-    -- Cat-file header navigation: `parent <sha>` (commit), `tree <sha>`
-    -- (commit / tag), `object <sha>` (tag's referent) all reference
-    -- another git object.
     local sha = line:match("^commit (%x+)$")
         or line:match("^parent (%x+)$")
         or line:match("^tree (%x+)$")
@@ -382,12 +366,8 @@ function M.open_under_cursor()
         return true
     end
 
-    -- Tree-entry navigation: `<mode> <type> <sha>\t<name>`. Blobs are
-    -- routed by path so the URI carries the entry name and filetype
-    -- detection picks it up. Subtrees navigate by sha so the resulting
-    -- buffer's `git_ref` is the subtree's own sha (correct anchor for
-    -- relative path navigation within it). Other types (submodule
-    -- commit refs, tags) also navigate by sha.
+    -- Blobs navigate by path so the URI carries the entry name (filetype
+    -- detection wants the extension). Other types navigate by sha.
     local entry_type, entry_sha, entry_name =
         line:match("^%d+ (%w+) (%x+)\t(.+)$")
     if entry_sha then