style(gitcommit): improve code comments and docstrings

- update comments and docstrings for clarity and consistency across buffer, generator, git, init, and ui modules
- rephrase and simplify inline comments to enhance readability
- standardize parameter descriptions and function documentation for better maintainability

Author: jinzhongjia

lua/codecompanion/_extensions/gitcommit/buffer.lua

@@ -17,35 +17,35 @@ local default_config = {
 local config = {}
 
 ---Setup buffer keymaps for gitcommit filetype
----@param opts? CodeCompanion.GitCommit.ExtensionOpts.Buffer Configuration options
+---@param opts? CodeCompanion.GitCommit.ExtensionOpts.Buffer Config options
 function Buffer.setup(opts)
   config = vim.tbl_deep_extend("force", default_config, opts or {})
 
   if not config.enabled then
     return
   end
 
-  -- Create autocommand for gitcommit filetype
+  -- Create autocommand for gitcommit
   vim.api.nvim_create_autocmd("FileType", {
     pattern = "gitcommit",
     callback = function(event)
       Buffer._setup_gitcommit_keymap(event.buf)
 
       if config.auto_generate then
-        -- Auto-generation autocommand triggers once when entering gitcommit window
-        -- This avoids race conditions with plugins like neogit that manage multiple windows
-        -- Skip auto-generation during git amend to preserve user's intent to modify existing commit
+        -- Auto-generation triggers once when entering gitcommit window
+        -- Avoids race conditions with plugins like neogit
+        -- Skip auto-generation during git amend to preserve user intent
         vim.api.nvim_create_autocmd("WinEnter", {
           buffer = event.buf,
           once = true,
           callback = function(args)
-            -- Defer execution to ensure other plugins (like neogit) have finished UI setup
+            -- Defer execution to ensure other plugins finish UI setup
             vim.defer_fn(function()
               if not vim.api.nvim_buf_is_valid(args.buf) then
                 return
               end
 
-              -- Check if buffer already has a commit message
+              -- Check if buffer already has commit message
               local lines = vim.api.nvim_buf_get_lines(args.buf, 0, -1, false)
               local has_message = false
               for _, line in ipairs(lines) do
@@ -55,9 +55,9 @@ function Buffer.setup(opts)
                 end
               end
 
-              -- Skip auto-generation in the following cases:
-              -- 1. Buffer already has a commit message
-              -- 2. We are in a git amend operation (user may want to keep existing message)
+              -- Skip auto-generation if:
+              -- 1. Buffer already has commit message
+              -- 2. In git amend operation (user may want to keep existing message)
               local should_skip_amend = config.skip_auto_generate_on_amend and Git.is_amending()
               if not has_message and not should_skip_amend then
                 Buffer._generate_and_insert_commit_message(args.buf)
@@ -72,10 +72,10 @@ function Buffer.setup(opts)
   })
 end
 
----Setup keymap for specific gitcommit buffer
+---Setup keymap for gitcommit buffer
 ---@param bufnr number Buffer number
 function Buffer._setup_gitcommit_keymap(bufnr)
-  -- Only set keymap if buffer is modifiable and in gitcommit filetype
+  -- Only set keymap if buffer is valid
   if not vim.api.nvim_buf_is_valid(bufnr) then
     return
   end
@@ -93,13 +93,13 @@ end
 ---Generate commit message and insert into gitcommit buffer
 ---@param bufnr number Buffer number
 function Buffer._generate_and_insert_commit_message(bufnr)
-  -- Check if we're in a git repository
+  -- Check git repository
   if not Git.is_repository() then
     vim.notify("Not in a git repository", vim.log.levels.ERROR)
     return
   end
 
-  -- Get relevant changes (staged or amend)
+  -- Get changes for commit
   local diff, context = Git.get_contextual_diff()
   if not diff then
     local msg
@@ -115,14 +115,14 @@ function Buffer._generate_and_insert_commit_message(bufnr)
   Langs.select_lang(function(lang)
     vim.notify("Generating commit message...", vim.log.levels.INFO)
 
-    -- Get commit history if enabled
+    -- Get commit history for context
     local commit_history = nil
     local git_config = Git.get_config and Git.get_config() or {}
     if git_config.use_commit_history then
       commit_history = Git.get_commit_history(git_config.commit_history_count)
     end
 
-    -- Generate commit message using LLM
+    -- Generate commit message
     Generator.generate_commit_message(diff, lang, commit_history, function(result, error)
       if error then
         vim.notify("Failed to generate commit message: " .. error, vim.log.levels.ERROR)
@@ -150,15 +150,15 @@ function Buffer._insert_commit_message(bufnr, message)
   -- Get current buffer content
   local lines = vim.api.nvim_buf_get_lines(bufnr, 0, -1, false)
 
-  -- Find the first line that doesn't start with # (comment)
-  -- This is where we'll insert the commit message
+  -- Find first line that doesn't start with # (comment)
+  -- This is where we'll insert commit message
   local insert_line = 0
   for i, line in ipairs(lines) do
     if not line:match("^%s*#") and vim.trim(line) == "" then
       insert_line = i - 1
       break
     elseif not line:match("^%s*#") and vim.trim(line) ~= "" then
-      -- Found non-comment, non-empty line, insert before it
+      -- Found non-comment, non-empty line, insert before
       insert_line = i - 1
       break
     end
@@ -167,7 +167,7 @@ function Buffer._insert_commit_message(bufnr, message)
   -- Split message into lines
   local message_lines = vim.split(message, "\n")
 
-  -- Remove existing commit message if present (before first comment line)
+  -- Remove existing commit message if present
   local first_comment_line = nil
   for i, line in ipairs(lines) do
     if line:match("^%s*#") then
@@ -177,29 +177,29 @@ function Buffer._insert_commit_message(bufnr, message)
   end
 
   if first_comment_line then
-    -- Remove non-comment lines before the first comment
+    -- Remove non-comment lines before first comment
     local non_comment_lines = {}
     for i = 1, first_comment_line do
       if not lines[i]:match("^%s*#") and vim.trim(lines[i]) ~= "" then
-        -- This is a non-comment line, it might be an existing commit message
+        -- This is non-comment line, might be existing commit message
       else
         table.insert(non_comment_lines, lines[i])
       end
     end
 
-    -- Clear the buffer and insert new content
+    -- Clear buffer and insert new content
     vim.api.nvim_buf_set_lines(bufnr, 0, first_comment_line, false, {})
   end
 
-  -- Insert the new commit message at the beginning
+  -- Insert new commit message at beginning
   vim.api.nvim_buf_set_lines(bufnr, 0, 0, false, message_lines)
 
-  -- Add an empty line after the commit message if it doesn't end with one
+  -- Add empty line after commit message if needed
   if #message_lines > 0 and message_lines[#message_lines] ~= "" then
     vim.api.nvim_buf_set_lines(bufnr, #message_lines, #message_lines, false, { "" })
   end
 
-  -- Move cursor to the beginning of the commit message
+  -- Move cursor to beginning of commit message
   vim.api.nvim_win_set_cursor(0, { 1, 0 })
 
   vim.notify("Commit message generated and inserted!", vim.log.levels.INFO)

lua/codecompanion/_extensions/gitcommit/generator.lua

@@ -64,17 +64,17 @@ end
 
 ---Create prompt for commit message generation
 ---@param diff string The git diff to include in prompt
----@param commit_history? string[] Array of recent commit messages for context (optional)
+---@param commit_history? string[] Recent commit messages for context (optional)
 function Generator._create_prompt(diff, lang, commit_history)
-  -- Build the history context section
+  -- Build history context section
   local history_context = ""
   if commit_history and #commit_history > 0 then
     history_context = "\nRECENT COMMIT HISTORY (for style reference):\n"
     for i, commit_msg in ipairs(commit_history) do
       history_context = history_context .. string.format("%d. %s\n", i, commit_msg)
     end
     history_context = history_context
-      .. "\nAnalyze the above commit history to understand the project's commit style, tone, and format patterns. Use this as guidance to maintain consistency.\n"
+      .. "\nAnalyze commit history to understand project style, tone, and format patterns. Use this for consistency.\n"
   end
 
   return string.format(
@@ -127,7 +127,7 @@ Return ONLY the commit message in the exact format shown above.]],
 end
 
 ---Handle LLM response
----@param err table|nil Error from request
+---@param err table|nil Request error
 ---@param data table|nil Response data
 ---@param adapter table The adapter used
 ---@param callback fun(result: string|nil, error: string|nil) Callback function
@@ -138,12 +138,12 @@ function Generator._handle_response(err, data, adapter, callback)
     return callback(nil, error_msg)
   end
 
-  -- Check for empty or invalid data
+  -- Check for empty/invalid data
   if not data then
     return callback(nil, "No response received from LLM")
   end
 
-  -- Process successful response
+  -- Process response
   if data then
     local result = adapter.handlers.chat_output(adapter, data)
     if result and result.status then