refactor: remove worthless comments that describe obvious code

- Remove comments that just describe what code does rather than why
- Keep valuable LuaDoc annotations and explanatory comments
- Remove obvious descriptive comments like "Create directory", "Write to file", etc.
- Preserve comments that explain business logic, error handling rationale, or complex algorithms
- All tests continue passing (181 successes)

Change-Id: Ia019bc6889b7ef969afd49e699d09b3ffaafd8e4
Signed-off-by: Thomas Kosiewski <[email protected]>

Author: ThomasK33

lua/claudecode/config.lua

@@ -17,9 +17,7 @@ M.defaults = {
   },
 }
 
---- Validates the provided configuration table.
--- Ensures that all configuration options are of the correct type and within valid ranges.
--- @param config table The configuration table to validate.
+--- @param config table The configuration table to validate.
 -- @return boolean true if the configuration is valid.
 -- @error string if any configuration option is invalid.
 function M.validate(config)
@@ -64,10 +62,7 @@ function M.validate(config)
   return true
 end
 
---- Applies user configuration on top of default settings and validates the result.
--- Merges the user-provided configuration with the default configuration,
--- then validates the merged configuration.
--- @param user_config table|nil The user-provided configuration table.
+--- @param user_config table|nil The user-provided configuration table.
 -- @return table The final, validated configuration table.
 function M.apply(user_config)
   local config = vim.deepcopy(M.defaults)

lua/claudecode/diff.lua

@@ -641,7 +641,6 @@ function M._create_diff_view_from_window(target_window, old_file_path, new_buffe
     vim.api.nvim_buf_set_option(empty_buffer, "modifiable", false)
     vim.api.nvim_buf_set_option(empty_buffer, "readonly", true)
 
-    -- Set the empty buffer in the target window
     vim.api.nvim_win_set_buf(target_window, empty_buffer)
     original_buffer = empty_buffer
   else
@@ -872,7 +871,6 @@ function M._setup_blocking_diff(params, resolution_callback)
   vim.api.nvim_buf_set_name(new_buffer, new_unique_name)
   vim.api.nvim_buf_set_lines(new_buffer, 0, -1, false, vim.split(params.new_file_contents, "\n"))
 
-  -- Set buffer options for the new content buffer
   vim.api.nvim_buf_set_option(new_buffer, "buftype", "acwrite") -- Allows saving but stays as scratch-like
   vim.api.nvim_buf_set_option(new_buffer, "modifiable", true)
 

lua/claudecode/integrations.lua

@@ -105,7 +105,6 @@ function M._get_neotree_selection()
           end_pos = cursor_pos
         end
       end
-      -- No valid visual marks found
 
       if end_pos < start_pos then
         start_pos, end_pos = end_pos, start_pos
@@ -120,12 +119,9 @@ function M._get_neotree_selection()
           if node.type and node.type ~= "message" then
             table.insert(selected_nodes, node)
           end
-          -- Message nodes not included in selection
         end
-        -- No node found at this line
       end
 
-      -- Extract file paths from selected nodes with enhanced validation
 
       for i, node in ipairs(selected_nodes) do
         -- Enhanced validation: check for file type and valid path
@@ -141,13 +137,9 @@ function M._get_neotree_selection()
       if #files > 0 then
         return files, nil
       end
-      -- No files found in visual selection
     end
-    -- Not in correct neo-tree window
   end
-  -- Not in visual mode
 
-  -- Method 2: Try neo-tree's built-in selection methods
 
   if state.tree then
     local selection = nil
@@ -170,13 +162,9 @@ function M._get_neotree_selection()
       if #files > 0 then
         return files, nil
       end
-      -- No files found in selection
     end
-    -- No selection available
   end
-  -- No tree available
 
-  -- Fall back to current node under cursor
 
   if state.tree then
     local node = state.tree:get_node()
@@ -187,11 +175,8 @@ function M._get_neotree_selection()
       elseif node.type == "directory" and node.path then
         return { node.path }, nil
       end
-      -- Invalid node type or path
     end
-    -- No cursor node found
   end
-  -- No tree state available
 
   return {}, "No file found under cursor"
 end

lua/claudecode/lockfile.lua

@@ -18,7 +18,6 @@ function M.create(port)
     return false, "Invalid port number"
   end
 
-  -- Ensure lock directory exists
   local ok, err = pcall(function()
     return vim.fn.mkdir(M.lock_dir, "p")
   end)
@@ -27,10 +26,8 @@ function M.create(port)
     return false, "Failed to create lock directory: " .. (err or "unknown error")
   end
 
-  -- Generate lock file path
   local lock_path = M.lock_dir .. "/" .. port .. ".lock"
 
-  -- Get workspace folders
   local workspace_folders = M.get_workspace_folders()
 
   -- Prepare lock file content
@@ -41,7 +38,6 @@ function M.create(port)
     transport = "ws",
   }
 
-  -- Convert to JSON with error handling
   local json
   local ok_json, json_err = pcall(function()
     json = vim.json.encode(lock_content)
@@ -52,7 +48,6 @@ function M.create(port)
     return false, "Failed to encode lock file content: " .. (json_err or "unknown error")
   end
 
-  -- Write to file
   local file = io.open(lock_path, "w")
   if not file then
     return false, "Failed to create lock file: " .. lock_path
@@ -64,7 +59,6 @@ function M.create(port)
   end)
 
   if not write_ok then
-    -- Try to close file if still open
     pcall(function()
       file:close()
     end)
@@ -85,12 +79,10 @@ function M.remove(port)
 
   local lock_path = M.lock_dir .. "/" .. port .. ".lock"
 
-  -- Check if file exists
   if vim.fn.filereadable(lock_path) == 0 then
     return false, "Lock file does not exist: " .. lock_path
   end
 
-  -- Remove the file with error handling
   local ok, err = pcall(function()
     return os.remove(lock_path)
   end)
@@ -111,7 +103,6 @@ function M.update(port)
     return false, "Invalid port number"
   end
 
-  -- First remove existing lock file if it exists
   local exists = vim.fn.filereadable(M.lock_dir .. "/" .. port .. ".lock") == 1
   if exists then
     local remove_ok, remove_err = M.remove(port)
@@ -120,7 +111,6 @@ function M.update(port)
     end
   end
 
-  -- Then create a new one
   return M.create(port)
 end
 

lua/claudecode/logger.lua

@@ -20,8 +20,7 @@ local level_values = {
 
 local current_log_level_value = M.levels.INFO
 
---- Initializes the logger with the provided configuration.
--- @param plugin_config table The configuration table (e.g., from claudecode.init.state.config).
+--- @param plugin_config table The configuration table (e.g., from claudecode.init.state.config).
 function M.setup(plugin_config)
   local conf = plugin_config
 
@@ -83,8 +82,7 @@ local function log(level, component, message_parts)
   end
 end
 
---- Logs a message at the ERROR level.
--- @param component string|nil Optional component/module name.
+--- @param component string|nil Optional component/module name.
 -- @param ... any Varargs representing parts of the message.
 function M.error(component, ...)
   if type(component) ~= "string" then
@@ -94,8 +92,7 @@ function M.error(component, ...)
   end
 end
 
---- Logs a message at the WARN level.
--- @param component string|nil Optional component/module name.
+--- @param component string|nil Optional component/module name.
 -- @param ... any Varargs representing parts of the message.
 function M.warn(component, ...)
   if type(component) ~= "string" then
@@ -105,8 +102,7 @@ function M.warn(component, ...)
   end
 end
 
---- Logs a message at the INFO level.
--- @param component string|nil Optional component/module name.
+--- @param component string|nil Optional component/module name.
 -- @param ... any Varargs representing parts of the message.
 function M.info(component, ...)
   if type(component) ~= "string" then
@@ -116,8 +112,7 @@ function M.info(component, ...)
   end
 end
 
---- Logs a message at the DEBUG level.
--- @param component string|nil Optional component/module name.
+--- @param component string|nil Optional component/module name.
 -- @param ... any Varargs representing parts of the message.
 function M.debug(component, ...)
   if type(component) ~= "string" then
@@ -127,8 +122,7 @@ function M.debug(component, ...)
   end
 end
 
---- Logs a message at the TRACE level.
--- @param component string|nil Optional component/module name.
+--- @param component string|nil Optional component/module name.
 -- @param ... any Varargs representing parts of the message.
 function M.trace(component, ...)
   if type(component) ~= "string" then

lua/claudecode/server/frame.lua

@@ -26,7 +26,6 @@ M.OPCODE = {
 ---@return WebSocketFrame|nil frame The parsed frame, or nil if incomplete/invalid
 ---@return number bytes_consumed Number of bytes consumed from input
 function M.parse_frame(data)
-  -- Input validation
   if type(data) ~= "string" then
     return nil, 0
   end
@@ -46,14 +45,12 @@ function M.parse_frame(data)
 
   pos = pos + 2
 
-  -- Parse first byte
   local fin = math.floor(byte1 / 128) == 1
   local rsv1 = math.floor((byte1 % 128) / 64) == 1
   local rsv2 = math.floor((byte1 % 64) / 32) == 1
   local rsv3 = math.floor((byte1 % 32) / 16) == 1
   local opcode = byte1 % 16
 
-  -- Parse second byte
   local masked = math.floor(byte2 / 128) == 1
   local payload_len = byte2 % 128
 

lua/claudecode/server/tcp.lua

@@ -22,7 +22,6 @@ function M.find_available_port(min_port, max_port)
     return nil -- Or handle error appropriately
   end
 
-  -- Create a list of ports in the range
   local ports = {}
   for i = min_port, max_port do
     table.insert(ports, i)
@@ -51,13 +50,11 @@ end
 ---@return TCPServer|nil server The server object, or nil on error
 ---@return string|nil error Error message if failed
 function M.create_server(config, callbacks)
-  -- Find available port
   local port = M.find_available_port(config.port_range.min, config.port_range.max)
   if not port then
     return nil, "No available ports in range " .. config.port_range.min .. "-" .. config.port_range.max
   end
 
-  -- Create TCP server
   local tcp_server = vim.loop.new_tcp()
   if not tcp_server then
     return nil, "Failed to create TCP server"
@@ -74,7 +71,6 @@ function M.create_server(config, callbacks)
     on_error = callbacks.on_error or function() end,
   }
 
-  -- Bind to port
   local bind_success, bind_err = tcp_server:bind("127.0.0.1", port)
   if not bind_success then
     tcp_server:close()

lua/claudecode/terminal.lua

@@ -33,9 +33,7 @@ local managed_fallback_terminal_winid = nil
 local managed_fallback_terminal_jobid = nil
 local native_term_tip_shown = false
 
--- Determines the command to run in the terminal.
 -- Uses the `terminal_cmd` from the module's configuration, or defaults to "claude".
--- @local
 -- @return string The command to execute.
 local function get_claude_command()
   local cmd_from_config = term_module_config.terminal_cmd
@@ -91,7 +89,6 @@ function M.setup(user_term_config, p_terminal_cmd)
 end
 
 --- Determines the effective terminal provider based on configuration and availability.
--- @local
 -- @return string "snacks" or "native"
 local function get_effective_terminal_provider()
   if term_module_config.provider == "snacks" then
@@ -117,8 +114,6 @@ local function get_effective_terminal_provider()
   end
 end
 
---- Cleans up state variables for the fallback terminal.
--- @local
 local function cleanup_fallback_terminal_state()
   managed_fallback_terminal_bufnr = nil
   managed_fallback_terminal_winid = nil
@@ -127,7 +122,6 @@ end
 
 --- Checks if the managed fallback terminal is currently valid (window and buffer exist).
 -- Cleans up state if invalid.
--- @local
 -- @return boolean True if valid, false otherwise.
 local function is_fallback_terminal_valid()
   -- First check if we have a valid buffer
@@ -158,7 +152,6 @@ local function is_fallback_terminal_valid()
 end
 
 --- Opens a new terminal using native Neovim functions.
--- @local
 -- @param cmd_string string The command string to run.
 -- @param env_table table Environment variables for the command.
 -- @param effective_term_config table Configuration for split_side and split_width_percentage.
@@ -252,7 +245,6 @@ local function open_fallback_terminal(cmd_string, env_table, effective_term_conf
 end
 
 --- Closes the managed fallback terminal if it's open and valid.
--- @local
 local function close_fallback_terminal()
   if is_fallback_terminal_valid() then
     -- Closing the window should trigger on_exit of the job if the process is still running,
@@ -265,7 +257,6 @@ local function close_fallback_terminal()
 end
 
 --- Focuses the managed fallback terminal if it's open and valid.
--- @local
 local function focus_fallback_terminal()
   if is_fallback_terminal_valid() then
     vim.api.nvim_set_current_win(managed_fallback_terminal_winid)
@@ -275,7 +266,6 @@ end
 
 --- Builds the effective terminal configuration by merging module defaults with runtime overrides.
 -- Used by the native fallback.
--- @local
 -- @param opts_override table (optional) Overrides for terminal appearance (split_side, split_width_percentage).
 -- @return table The effective terminal configuration.
 local function build_effective_term_config(opts_override)
@@ -304,7 +294,6 @@ end
 --- Builds the options table for Snacks.terminal.
 -- This function merges the module's current terminal configuration
 -- with any runtime overrides provided specifically for an open/toggle action.
--- @local
 -- @param effective_term_config_for_snacks table Pre-calculated effective config for split_side, width.
 -- @param env_table table Environment variables for the command.
 -- @return table The options table for Snacks.
@@ -329,7 +318,6 @@ local function build_snacks_opts(effective_term_config_for_snacks, env_table)
 end
 
 --- Gets the base claude command string and necessary environment variables.
--- @local
 -- @return string|nil cmd_string The command string, or nil on failure.
 -- @return table|nil env_table The environment variables table, or nil on failure.
 local function get_claude_command_and_env()
@@ -355,7 +343,6 @@ local function get_claude_command_and_env()
 end
 
 --- Find any existing Claude Code terminal buffer by checking terminal job command
--- @local
 -- @return number|nil Buffer number if found, nil otherwise
 local function find_existing_claude_terminal()
   local buffers = vim.api.nvim_list_bufs()

lua/claudecode/tools/init.lua

@@ -172,23 +172,5 @@ function M.handle_invoke(client, params) -- client needed for blocking tools
   return { result = handler_return_val1 }
 end
 
--- Removed M.open_file function, its logic is now in lua/claudecode/tools/impl/open_file.lua
-
--- Removed M.get_diagnostics function, its logic is now in lua/claudecode/tools/impl/get_diagnostics.lua
-
--- Removed M.get_open_editors function, its logic is now in lua/claudecode/tools/impl/get_open_editors.lua
-
--- Removed M.get_workspace_folders function, its logic is now in lua/claudecode/tools/impl/get_workspace_folders.lua
-
--- Removed M.get_current_selection function, its logic is now in lua/claudecode/tools/impl/get_current_selection.lua
--- Removed M.get_latest_selection function as it was redundant with get_current_selection's new implementation
-
--- Removed M.check_document_dirty function, its logic is now in lua/claudecode/tools/impl/check_document_dirty.lua
-
--- Removed M.save_document function, its logic is now in lua/claudecode/tools/impl/save_document.lua
-
--- Removed M.open_diff function, its logic is now in lua/claudecode/tools/impl/open_diff.lua
-
--- Removed M.close_buffer_by_name function, its logic is now in lua/claudecode/tools/impl/close_buffer_by_name.lua
 
 return M